Writing software documentation is much like juggling porcupines while walking a tight rope in 50 mile-per-hour winds. Your attention is constantly divided and the situation is always changing. The moment you finalize your work, a new feature appears in the software, and you find yourself scrambling to document it in time for the product release.
So, how do you go about writing technical manuals for software without going insane?
Here are some guidelines you can follow to maintain your sanity when writing software documentation.
- Create and maintain a style guide. Style in technical writing can vary from one product to the next, and you'll save yourself a lot of grief by keeping notes regarding conventions.
- Keep your friends close and your SMEs closer. If you can promote open and frequent communication with developers, writing software documentation will be much easier. You won't be blind-sided as often by changes in the software.
- Install often. Don't waste time writing software documentation for an out-of-date version of the product.
- Make time for testing. Be sure to try out every procedure at least once to verify that the instructions are accurate.
- Talk to the Support staff. You'll be more effective at writing software documentation if you understand the problems users typically experience.
- Use templates. Have a template for each topic type (reference, FAQ, procedure, etc.) and use them for quickly fleshing out new topics.
- Invest in your tools. A feature-rich set of technical writing authoring tools will make the process of writing software documentation much smoother. A help authoring tool, such as Adobe RoboHelp or MadCap Flare, and a tool for print documentation, such as Adobe Framemaker, will suffice. Some XML-based authoring tools are capable of producing both printed documentation and help.
- Invest in your skills by learning from others. If you run into problems while writing software documentation, open up the MadCap Flare help or an Adobe RoboHelp manual and see if they've tackled the same situation. Find examples of great technical writing and emulate them.
- Stay organized. Learn to use project management software to track pending tasks and notes. Keep a manila folder for each project and fill it with printed copies of notes and important email messages. This is especially important when writing software documentation for multiple products at once.
- Keep a list of questions for SMEs. Your time with them will be more productive, and they will appreciate your respect for their busy schedules.
- Focus on your help navigation, table of contents, or index. There's no point in writing software documentation that users can't find. Enable full-text search, if possible.
- Prepare use cases, and compare your procedures to those use cases. Does your documentation cover all of the tasks your users need to complete? If not, fill in the missing content.
- Be specific. When writing software documentation you must be particularly clear about tasks the user must complete versus tasks that the software completes automatically. Ambiguous language will leave users scratching their heads or reaching for their telephones to call Support.
- Provide context. Writing software documentation isn't just about telling users what to do. You must also tell them why they would want to complete a task, and explain the desired outcome. This point is particularly important for anyone using a single-sourcing methodology where chunks of content are combined to create the final output. Be sure to provide context to show how those chunks of content are related and create a feeling of continuity.
- Verify that your documentation set is complete. Did you include accurate installation instructions? How about contact information for Customer Support? Does your product warrant a tutorial or interactive training? Writing software documentation often requires producing more than just a printed manual or online help.
- Leverage existing content. If your company provides a knowledgebase or support website, refer to it in your manuals. Use cross-references to guide users through all of the various forms of product documentation in an intelligent manner.
- Use a consistent design for your documentation. Users will adapt to your design and learn more effectively if you present content in a consistent and user-friendly manner.
- Delete unnecessary content. Writing software documentation isn't like writing a novel, and brevity will often result in improved clarity. However, don't leave out important information for the sake of being brief. Use as many words as necessary to accurately explain a concept, and no more.
- Find peer reviewers. Preferably, get another writer and a product developer to review your documentation. They will help sort out any technical inaccuracies, and improve the clarity of your writing.
- Revise often. The great thing about writing software documentation is that you usually have frequent opportunities to deliver updated content. Developers constantly ship newer versions to include the latest features. Take advantage of those updates and ship your latest improvements to the software manuals and help.
- Set some informal deadlines for yourself. Factor in time for documentation reviews, testing, and dealing with troublesome authoring tool issues. One of the difficulties of writing software documentation is the instability of product release schedules. By maintaining your own aggressive deadlines, you'll be more prepared if the company decides to ship the product two weeks earlier than planned.
- Have some fun. Play multiplayer games with the developers, or go out for a long lunch with your fellow technical authors. Writing software documentation is hard work. Don't burn yourself out.
Photo by Glenn Carstens-Peters on UnsplashI hope these tips make the process of writing software documentation a little less painless. If you're as crazy as the rest of us technical writers you might even enjoy it!