The First Steps to Writing Software Documentation

 By Jane Hoppen, published Apr 01, 2007

When writing software documentation, following a few basic processes when you begin will help to ensure that your document is complete and accurate. These processes include gathering existing documentation, reviewing the application, and interviewing subject-matter experts. This article covers the details on these processes as a way to launch you into this intriguing writing field.

Design Specifications
A design specification is also written before any development of an application begins. It serves as a guide for those involved in creating the application's user interface, such as designers, HTML programmers, and graphic artists. The design specification also includes information gathered by the project manager while interviewing the client to define clearly the presentation of the application.
Design specifications written for Intranet/Internet applications are often more detailed than those for software applications. Specifications often vary from client to client, but they generally include the following:

* Layout for application windows or Internet/Intranet pages
* Client designs to incorporate, including logo, artwork, colors
* Navigation features used for promoting user friendliness
* Layout for forms and reports
* Supplemental elements, such as ad banners, graphics, or links to be used on the application

The design specification is an excellent source regarding the look and feel of the application.

 

Technical Specifications
Technical specifications are written for software and Internet/Intranet applications, and those these specifications are not always written before development begins, you can try to gather from developers and system engineers any information that they might want to incorporate into the specifications. As with other specifications, these vary from client to client, but they generally include the following information:

* System requirements
* System architecture
* System components
* Directory structure
* File naming conventions
* Database table relationships
* Import/export processes
* Technical support
* Templates used

The technical specifications will give you a good understanding of how the application works, and will alert you to any user requirements that you should include in your guide.

 

The Walk-Through
Before you begin a walk-through, which consists of working through and using every window within the application, ask the client or project manager to clarify different user roles. For example, a payroll application might target three different users: preparers, approvers, and administrators. Each type of user will often have access to different modules of the application. After you identify user roles, you are ready to begin your walk-through to discover how the application functions. Remember to perform a walk-through for each user type. Keep thorough notes and a list of any questions you have regarding task completion, user functions, field input, warnings and messages, forms and reports, and processes.

As you walk through the application, you can begin an outline based on the following elements:

* Overall application layout
* Interaction between application modules
* Steps that users must perform to complete tasks
* Outcome of completing tasks or inputting information.

During your walk-through, note the different field types that the application uses, such as check boxes, text boxes, option buttons, and the parameters for each field. The parameters include the type of information that the user must enter into a field, as well as the format of the field information. For example, to enter a telephone number in a field, the user might be required to use the following format: ###-###-####. If the user enters the telephone number in any other way, an error message will display.

During the walk-through, you will often discover that selecting a particular function on one window uses another window to appear, often from a different module within the application. An excellent method for tracking the interaction of windows within an application is to draw diagrams that depict workflow.

When you finish your walk-through, review all of your notes, and then form lists of accumulated questions. You will find that different team members will be able to answer different questions. Team members will appreciate your efforts to ensure that they receive only the questions that pertain to them.

 

You can use screen captures in your user guide to add clarity for the user. Screen captures within documentation illustrate what is being described, and give users a visual reference to compare with what is on their own personal computers. You can use screen captures in a number of ways to make your documentation more complete and exact.

When you take screen captures, be sure that the field information that you capture is not real. Do not use screen captures from the production environment or live accounts. Create your own records for screen captures, if necessary. This will ensure that you do not reveal any of your client's confidential information. If you do create your own records, do not use your name or the names of relatives and friends; TV, movie, or cartoon character names; names that you think others might find humorous; or names that rhyme or are cute. These simple rules will ensure that you never affront any member of your target audience and that the guide is work oriented. Before you take screen captures for printed documents, change your desktop screen colors to a palette or colors that reproduce well in black and white print. The palette or colors also should show good contrast in black and white print. When you take screen captures for online deliverables (HTML or Help systems), change your desktop screen colors to a palette or colors that complement the color scheme of the online deliverable.

 

Interviewing Subject-Matter Experts
After performing the initial review of the application, compile a list of questions to determine which subject-matter experts are best suited to answer particular questions. The number of individuals involved in creating an application varies from project to project. If a large number are involved, ask the project manager to provide a primary point of contact for each group: developers, engineers, designers, and quality-assurance analysts.

 

System Engineers
Engineers are involved in the architecture and can provide you with any system requirements, such as memory, platforms, etc. System engineers can also provide any information you need regarding hardware, components, and configuration.

 

Designers
Designers create the application's user interface, and they can provide information on navigation and window interaction. Designers can also provide you with any image or banner specifications the user might need. For Internet/Intranet applications, the designers and the developers determine which browsers the application will be developed for and best function in, such as Internet Explorer 5 and Netscape Navigator 4.