Access to SMEs a key ingredient in a successful project

One of the most important steps that a client can take to ensure the successful and timely completion of a writing project is to make sure the technical documentation team has good access to subject matter experts (SME). All SMEs needed for the project should be considered part of a resource team that meets periodically and is kept up-to-date on the project. If management takes the project seriously, and intends to make sure it is successful, they will communicate by word and example that attendance at these meetings is a high priority. They will also make sure that team members are allocated time to spend working with the documentation team and given clear instructions that they are expected to cooperate and support the tech writers’ efforts.

Ideally, the documentation team is able to spend adequate time on-site, working directly with the SMEs. Several factors must be in place to make sure on-site time is used effectively. The SMEs must be available, and know they are expected to cooperate. From the tech writer’s perspective, having full-time access to an SME who has a wide range of knowledge and experience would be ideal. Sometimes that is possible. For example, I have worked closely with an experienced plant operator who was on a work accommodation. Unfortunately, he was often pulled away from working with me to assist with other projects and situations as they arose.

It’s important to remember that one SME does not have all the answers. SMEs participate in several phases of the project. In the data gathering phase the doc team brings together information about the plant and how it is operated. This includes facts, specifications, how equipment and systems work, tasks and procedures. The next phase includes fact verification, but also verification of policies. A third phase–validation–involves confirmation that the document is acceptable. A plant operator may be able to answer questions about facts and procedures, but he or she probably cannot provide definitive rulings on operating policies. Those answers may have to come from supervisory or management staff. Sometimes there can be differences of opinion on best practices. Who makes the final ruling on what is the best practice for a given procedure? Who validates a procedure as complying with company policy? Without access to the appropriate SME the technical writer’s hands are tied.

Developing procedures for water and wastewater

One of the most contentious and polarized issues I have come across regarding developing procedures is that of minimalist versus comprehensive content in standard operating procedures. Sit down with a group of plant operators and maintenance personnel and ask them what they would like to see in an SOP and then watch what happens. One camp wants a single sheet of paper with less than a dozen basic procedural steps. The other pushes for a comprehensive set of instructions suitable for standardizing the procedure and training new recruits.

I fall into that second camp–probably because of my training background. I see the value to making sure the document targets the lowest common denominator, and can be used to train (or retrain) anyone at any level of competence. That said, I like to include a simple checklist that the more experienced personnel can take with them into the field and use as necessary to make sure everything is covered.

The Greased Rubber Ball

Back when I was instructing electronics and instrumentation apprentices and technologists I liked to start each new batch of students with my “Greased Rubber Ball” theory of learning. I told them that their upcoming learning experience would be like trying to stay on top of a giant greased rubber ball. I suggested that if they did not take the situation seriously right from the start, they would easily slip off the ball. It would be most difficult to climb back on. I also suggested their best bet would be to buckle down and cling to the top of that ball, work hard and focus on keeping their balance. Silly though the analogy may be, I still think it paints a useful picture.

Now that I am primarily concerned with creating training materials, rather than delivering them, I can see the value in producing materials that help students maintain that focus, ensuring a successful learning experience.

Tech Writing for Process Industries

This being the first post on a new website/blog, I’m putting out an open invitation for responses from other tech writers–especially those who work in process industries. Writing is a lonely business at the best of times, but so far I haven’t met many writers who serve process industries. Anyone out there who would care to share their experiences?

Author-it for re-use and single sourcing

For almost two years we have been using Author-it for creating and publishing documents for a local water and wastewater utility. To say that learning AIT has been a challenge would be an understatement but we don’t regret making the move to this powerful program.

Author-it is a professional document creation application that allows content reuse and single source / multiple publishing.

Content re-use becomes a huge asset when you are creating a whole library of interrelated and overlapping documents. In our situation we started out by virtually re-writing an existing operations manual. Next we designed and wrote a whole series of standard operating procedures (SOP). There is significant overlap between these documents. The operations manual describes the processes, control systems, operational policy/techniques and then includes basic procedures. The SOPs focus in on the procedures, expanding them and providing additional detail. The operations manual and SOPs were then used as a basis for training materials. Content re-use allows us to re-use content objects in multiple documents. An added benefit is that when an object is edited or updated the content in all documents that use that object is updated as well.

Single sourcing enables us to create a document (focusing on content primarily) and then publish it to print formats (MSWord/pdf), web (various flavours of HTML) or even as help files. For this client we publish to print and HTML. As with many clients, hardcopy manuals are still preferred by most plant staff. But the ability to publish the same content to an internal website assists plant personnel with the transition to a version of the documentation that features hyperlinked tables of content, indicies, glossaries and links between documents.

We should say again that learning AIT has not been easy. The learning curve is steep, but the benefits are worth the effort. AIT is also an evolving software application (like many) and has had some bugs, especially in one of their major releases. We have worked through these and continue to be convinced that this is the best choice for our situation.