How to Write Software Manuals?

A good software manual helps the person using the software know about its features and utilities well. It can be used by anyone, like programmers, testers, internal user or an end user. Software manual writing is a skilful work and a good manual is very specific, relevant and concise, with no nonsense details. Here are some tips for writing a good software manual.

Decide What to Include

Software manuals act as a reference document for programmers who create the code and testers who test if the software works as is intended to. The appropriate information depends on the program concerned but may include the following too:

• Main files in the application – These may include files written by the development team, data accessed during the operation of the program and third-party utility programs.
• Functions – These include an explanation of each function or subroutine, and its range of input and output values.
• Variables and constants and their usage in the program
• Program structure – This may mean a description of individual modules and libraries of the program for a disc-based program, while it may mean description of pages using the files for a web application.

Determine the Purpose of the Manual

Though helping users to understand how to use the software is the main purpose of the manual, there can be other purposes too, like helping to market the software, improving the image of the company, and most importantly, decreasing costs for technical support. Sometimes, manuals are also necessary for complying with certain regulations or legal requirements. You will have to consider the purpose and create the manual accordingly.

Decide which Information should be within Program Code and which should be Separate

The more technical information is included within the program code, the easier will it be to revise and maintain along with the code, and also to include various versions of the original software. At least, information within the source code should explain the intention of functions, subroutines, variables and constants.

• If the source code is lengthy, it can be given in form of a help file which can be searched with keywords. This is an advantage when the program logic is divided in several pages and includes many supplemental files, similar to certain web applications.
• Some languages like Java and .NET Framework have their own rules for documentation code. In such a condition, follow those rules regarding how much information should be included in the source code.

Choose Correct Documentation Tool

This is determined, to some extent, by the language of the code, whether it is C++, Visual Basic, C#, PHP or Java, as particular tools exist for these and others. In other situations, the tool is determined by the kind of documentation needed.

• Microsoft Word word-processing programs are enough for creating individual text files of documentation, if the documentation is quite short and simple. For long, complicated text files, tools like Adobe FrameMaker are preferred.
• Help files for writing source code can be created with any tool like RoboHelp, Doc-To-Help, HelpLogix, MadCap Flare or Help and Manual.

Some More Tips

• The text in the manual should be arranged to facilitate easy reading and graphics should be placed near the text relevantly. Break down the topics and sections logically. Each section should deal with a single issue. Associated issues can be dealt with in the “see also” section or hyperlinks as required.
• All of the documentation tools given above can be supplemented with a program creating screenshots, like Snagit, if you require many screenshots. In other cases, screenshots must be used to explain the application and not to dazzle the reader.
• Addressing users with second person “you” is preferable than the third person like “users”.