Thursday

Write New Feature Documentation

Today I set aside some time to do some actual writing. I already met with the feature developers, so I have a lot of notes that I can work from. However, I realize I need to ask the developers some more questions, so I sit down to talk with one of them. It's tricky asking questions sometimes; each developer responds differently to each question, and I have to figure out which questions give me the information I want.

Soon I have everything I need to get started writing. I find a perfect place for this new content in the user manual. I think about what chapter title and section headings best communicate my information. I decide to use gerunds as headings, which inform readers what they will learn or accomplish in the chapter. This design is one component of the task-based approach to documentation.

I begin the chapter with just enough background material to put the feature in context. For more information, I reference a well-known textbook the developer told me about. After that, I include a tutorial that introduces several key terms and ideas.

From there, I discuss how the feature works. Because customers can use LabVIEW in so many different ways, I can't anticipate exactly what a customer will need from the documentation. I want to provide our customers with as much information as possible.

After I finish the first draft, I put it aside and work on other projects for a little while before proofreading. It's always a good idea to put some mental distance between draft revisions. Doing so gives your brain a chance to process what you've just written.