Documenting New Software Features (Information Gathering)

Tools Used: Email, Net Meeting, WebEx, Notetab Pro text editor, Wikipedia (!), knowledge bases, Gimp graphics program, screencapture programs
Writing Samples: Screenshot #1, Screenshot #2 (and other writing samples).

A technical writer’s primary job is to document new procedures or product features. Whenever the hardware people at Texas Instruments brought out the next generation of digital signal processors (DSP), the DSP programming software had to be enhanced to help engineers use those features. That meant I (and the other people on my team) had to learn about new features and to incorporate them into existing documentation.

How does one do this? This task can be broken down into several smaller ones:

  1. Learn exactly what features were new. (Believe it or not, this was often difficult to ascertain)!
  2. Attend meetings and look over project specifications and requirements documents.
  3. Identify people who would be suitable subject matter experts (SMEs)
  4. Arrange for SW demos when possible.
  5. Determine whether I should write the documentation from scratch or request a SME to write a rough draft.
  6. Determine which aspect to the new technology needed documenting and which aspects didn’t.
  7. Provide a scope & schedule to the product manager.

Here are some of the challenges I faced:  (both at Texas Instruments and my other jobs)>

Writing for highly-skilled professionals. By definition, technical writers know significantly less about a subject than product designers (and often even end users). It’s easy for technical writers to fall into the trap of writing from the technical writer’s point of view instead of the end user’s point of view. To avoid this, the writer should avoid getting bogged down by introductory information they had to learn themselves and instead concentrate on things specific to the company’s tool which might be immediately useful to engineers. Conversely, when writing documentation for the general user, it is easy for the technical writer to get too technical or too detailed. Part of the art of technical documentation is knowing the right amount of detail to convey depending on the user.
Using the subject matter expert’s time effectively. For example, when do you call and when do you send email? And when should you try to learn things on your own? Experience has taught me that engineers often have competing priorities. Documentation can in fact be a low priority for an engineer! For my TI projects, I had to communicate with engineers on three separate continents. Developing a tolerance for delays is necessary; often if you multitask, you can switch gears and work on other tasks while you’re waiting.
Doing your homework. To receive good information, you have to ask smart questions. In other words, you have to ask questions and then follow up questions as well. Uncovering what the engineer forgot to tell you requires diligence, patience and persistence. It is unwise and impractical to drown your subject matter expert in open-ended questions. Among the strategies I use: doing background research on the web, reading existing documention and project documents beforehand, forwarding a draft copy to the SME and wait for him/her to tear it apart, scheduling face-to-face meetings or telephone calls or Net Meetings when completely in the dark.
Staying in the loop. Junior technical writers have a hard time getting invited to meetings and being on the cc list for important discussions. I’ve learned the hard way that it’s better to get invited to too many meetings than too few.
Allowing sufficient time for review. Writing technical documents often requires the SME or a whole team to look over your documentation. At my TI job, sometimes new features were added at the last minute, or engineers didn’t have time to do a review. That was normal. Oddly, it’s possible to get too bogged down by the review process. If you send too many versions to engineers too many times, they become confused or not motivated enough to provide useful feedback.