Documenting Software Applications

As a result of more than 15 years working as a Technical Writer on a variety of industrial sectors I came up with road map to develop accurate and friendly documentation for technical audiences. In this article I would like to share some of my experience in producing a variety of User Guides and Online Help systems for software systems.

I have devised a road map to help anyone get a successful documentation project review. 

Stage 1 - Development Strategy

Stage 2 - User Requirements

Stage 3 - Documentation Project Requirements

Stage 4 - Define Your Documentation Project

Stage 5 - Design Approach

Stage 6 - Documentation Production

Stage 7 - Documentation Reviews

Stage 8 - Documentation Delivery

Stage 9 - Documentation Management

The following sections will describe in detail each stage according to my experience in the field.

Stage 1 - Development Strategy

• Background Information Gathering.
• Define the scope of the documentation project.
• Define documentation project requirements.
• Define documentation production strategy.
• Define user requirements (refer to Stage 2). 

Stage 2 - User Requirements

•  What is the target audience?
  a) People already familiar with the system? Upgrade users?
  b) Admin users?
  c) Operator users? With/Without technical background?
• What the end user is expecting to get? A procedural or a how to guide?
• Is there any workflow in use to based upon?

<In Progress>

Stage 3 - Documentation Project Requirements

•  Define your Tools for the project:
  a) Image manipulation tool - in my case I prefer my old PaintShop Pro, which is portable and very easy to use, particularly to create/edit buttons, menu options, toolbars, etc.
  b) HAT tool - in my case I prefer Adobe RoboHelp.
  c) You may need a digital camera to take photos of equipment - I use my iPhone which provide the definition and sharpness I need most of the time.

<In Progress>

Stage 4 - Define Your Documentation Project Environment

•  Define your Project deliverables and schedule in sync with the SDLC.
• Setup your Project in RoboHelp (or your preferable HAT).
• Define your Project folder in the local drive and the back on the Network.
• Define your Project repository (use MS SharePoint if you do not have other CMS).
• Define your Project file name convention for documents and images (if your company don't have one).
• Require a copy of the software to run in your local machine, if possible, to make easier to test drive it and take required screenshots using your own tools.

 <In Progress>

Stage 5 - Design Approach

• Gather Information on Company Standards for Documentation.
• Gather Information on Existing Technical Documentation.
• Gather Company Requirements and Documentation Schedules.
• Check Existing Templates Requiring Improvements to meet the Software Project Requirements.
• Create New Templates as Required to Meet Project Requirements.
• Conform Document Layout Matching Corporate Image.
• Add Review History to the document.
• Add copyright notices.
• Add conventions and signs used in the document. 

Stage 6 - Documentation Production

• Fix document template styles.
• Work out the manual content outline.
• Prepare a Table of Contents, Table of Figures and Table of Tables.
• Take notes about requirements to start the software.
  a) It requires previous configuration?
  b) It requires any previous preparation?
  c) It requires test sample data (in case of databases)?
• Start to run the software by yourself to understand its functionality and to capture required screenshots to support your procedure descriptions.
• Notice related functionality between the GUI and the hardware and take notes about synchronous/asynchronous running.
• Take notes about error/exception messages and related procedures to work around errors or faults.
• Re-run every procedure against the software and hardware functionality. Take notes on work arounds and fatal errors.

<In Progress>

Stage 7 - Documentation Reviews

• Get a list of appointed reviewers from your Supervisor.
• Provide to each reviewer guidelines on how to mark up required or suggested changes in the document. Mention to them that they should comment pointing to a solution, not placing question marks. Also ask them about their preferences to comment on PDF or in printing.

<In Progress>

Stage 8 - Documentation Delivery

•  Contact the Marketing or related department about the final look and feel of the manual, asking for input.
• Prepare the manual for printing (in house or for a Printer house) or to output to PDF.
• Submit proof to whom it may concern.
• Get final approval for delivery.
• Delivery the document to the expected format and medium.

<In Progress>

Stage 9 - Documentation Management

• Select a Content Management System to store your manuals.
• Create a full backup of your project documentation before going ahead with a new project. Place it on a Network or CMS for future reference or use.

<In Progress>

Technical Writing Skills From Experience

Doing this type of analysis repeatedly enables a technical writer to notice things that even an engineer who developed the product may miss. Good technical writers have years of experience writing, re-writing, and then re-writing again to eliminate unnecessary words.

Observing the steps defined above, the TW will be able to:

• Create accurate, concise documentation that enables users to complete tasks independently.
• Organize information so that users quickly find what they need.
• Avoid confusing users with extraneous or out-of-place information.
• Avoid losing users due to inappropriate assumptions about their knowledge and background.
• Reduce support costs.
• Increase customer satisfaction.
• Demonstrate to customers that the guidance they need is accessible and easy to use.