Tips from the trenches

by Deb Lockwood

So, you've been given a bunch of source information, not a lot of direction, and told to produce a guide at the end of 90 days. Where do you begin? The subject of this month's question to the STC Rocky Mountain Chapter list was "How do you start a brand new printed-guide project?"

The consensus was that we do the following things, not necessarily in this order:

• Read the source materials.
• Attend training, take computer-based training, or read training materials.
• Get your hands on the thing you need to write about, whether it's a software application, hardware, or some other technology.
• Write a documentation plan.
• Draft an outline.
• Write out your questions.
• Attend design meetings.
• Jump in headfirst and write the first draft.
• Send the first draft to subject matter expert review.

The contributors' longer responses follow:

• The first thing I do is to clarify the audience, the purpose, and the scope of the document. I then gather the source information and check out training opportunities. After I feel like I'm totally immersed in the software application, I write an outline. I then flesh out the draft, starting with the section I feel like I know the most about.
• I delve into the source material enough to write about the subject. Then I present the writing to the SMEs so that I can get some feedback and answers to my questions. I usually end up with more source material to integrate. Expect the drafting process to be iterative; you will keep adding to it. Don't expect a section or a procedure to ever really be finished. You'll generally gather new input from writing other sections or procedures and will need to integrate new source material. And that's a good thing!
• To get started, I write a documentation plan. A documentation plan can be a real lifesaver as you near the deadline for a writing project. The interested parties read and approve the plan, either with changes or as is, and will either sign an approval sheet, or send me an email indicating approval. This step lessens the probability that I will have to rewrite or reorganize the material towards the end of the project.
• Here are the things I do. The order in which I do them may vary depending on the situation:
  • Read through the source material and create a list of questions.
  • Play with the product. I insist on having a copy of any software product or access to any product at a client's lab.
  • Ask one or more subject matter experts (SMEs) to demonstrate the product for me. I record these sessions on a small tape recorder, with everyone's permission, and ask lots of questions.
  • Start thinking about tasks the user has to perform and draft an outline based on those tasks. Add to my list of questions.
  • Send the outline for review once I feel it's the best I can do for a first draft.

  (Thank you to the following contributors: Theresa Daus-Weber, Linda Gallagher, and Kathy Ramsey.)