How to Write Software Documentation

Last Updated: January 19, 2021 References

Good software documentation, whether a specifications document for programmers and testers, a technical document for internal users, or software manuals and help files for end users, helps the person working with the software understand its features and functions. Good software documentation is specific, concise, and relevant, providing all the information important to the person using the software.^{[1]
X
Research source} Following are instructions on how to write software documentation for technical users and end users.

Method 1

Method 1 of 2:

Writing Software Documentation for Technical Users

1
Determine what information needs to be included. Software specification documents serve as reference manuals for designers of the user interface, programmers who write the code, and testers who verify that the software works as intended. The exact information depends on the program in question but may include any of the following:
- Key files within the application. This may include files created by the development team, databases accessed during the program's operation, and third-party utility programs.
- Functions and subroutines. This includes an explanation of what each function or subroutine does, including its range of input values and output values.
- Program variables and constants, and how they're used in the application.
- The overall program structure. For a disc-based application, this may mean describing the program's individual modules and libraries, while for a Web application, this may mean describing which pages use which files.
2
Decide how much of the documentation should be within the program code and how much should be separate from it. The more technical documentation is developed within the program's source code to begin with, the easier it will be to update and maintain along with the code, as well as to document various versions of the original application. At a minimum, documentation within the source code needs to explain the purpose of functions, subroutines, variables, and constants.^{[2]
X
Research source}
- If the source code is particularly lengthy, it can be documented in the form of a help file, which can be indexed or searched with keywords. This is a particular advantage for applications where the program logic is fragmented over many pages and includes a number of supplemental files, as with certain Web applications.
- Some programming languages, such as Java and the .NET Framework (Visual Basic.NET, C #), have their own standards for documenting code. In these cases, follow the standards as to how much of the documentation should be included with the source code.
Advertisement
3
Choose the appropriate documentation tool. To some extent, this is determined by the language the code is written in, be it C++, C#, Visual Basic, Java, or PHP, as specific tools exist for these and other languages. In other cases, the tool to use is determined by the type of documentation required.
- Word-processing programs for Microsoft Word are adequate for creating separate text files of documentation, as long as the documentation is fairly short and simple. For long, complex text files, many technical writers prefer a documentation tool such as Adobe FrameMaker.
- Help files for documenting source code can be produced with any help authoring tool, such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.

Method 2

Method 2 of 2:

Writing Software Documentation for End Users

1
Determine the business reasons for your documentation. Although the functional reason for documenting software is to help users understand how to use the application, there are other reasons as well, such as assisting in marketing the software, enhancing the company image, and most notably, reducing technical support costs.^{[3]
X
Research source} In some cases, documentation is necessary to comply with certain regulations or other legal requirements.
- In no case, however, should software documentation substitute for poor interface design. If an application screen requires reams of documentation to explain it, better to change the screen design to something more intuitive.
2
Understand the audience you're writing the documentation for. In most cases, software users have little knowledge of computers outside of the applications they use. There are several ways to determine how to address their needs with your documentation.
- Look at the job titles your prospective users hold. A system administrator is likely expert with a number of software applications, while a data entry clerk is more likely to know only the application he or she currently uses to enter data.
- Look at the users themselves. Although job titles generally indicate what people do, there can be considerable variation in how certain titles are used within a given organization. By interviewing prospective users, you can get a feel for whether your impressions of what their job title indicates are accurate or not.
- Look at existing documentation. Documentation for previous versions of software, as well as functional specifications, provide some indication as to what the user will need to know to use the program. Keep in mind, however, that end users are not as interested in how the program works as they are in what it can do for them.
- Identify the tasks needed to do the job, and what tasks need to be done before those tasks can be done.
3
Determine the appropriate format(s) for the documentation. Software documentation can be structured in 1 of 2 formats, the reference manual and the user guide. Sometimes, a combination of formats is the best approach.
- A reference manual format is devoted to explaining the individual features of a software application (button, tab, field, and dialog box) and how they work. Many help files are written in this format, particularly context-sensitive help that displays a relevant topic whenever a user clicks the Help button on a particular screen.^{[4]
  X
  Research source}
- A user guide format explains how to use the software to perform a particular task. User guides are often formatted as printed guides or PDFs, although some help files include topics on how to perform particular tasks. (These help topics are usually not context-sensitive, although they may be hyperlinked to from topics that are.) User guides often take the form of tutorials, with a summary of the tasks to be performed in the introduction and instructions given in numbered steps.^{[5]
  X
  Research source}
4
Decide what form(s) the documentation should take. Software documentation for end users can take 1 or several of many forms: printed manuals, PDF documents, help files, or online help. Each form is designed to show the user how to use each of the program's functions, whether in the form of a walkthrough or a tutorial; in the case of help files and online help, this may include demonstration videos as well as text and still graphics.
- Help files and online help should be indexed and keyword-searchable to allow users to quickly find the information they're looking for. Although help file authoring tools can generate indexes automatically, it is often better to create the index manually, using terms users are likely to search for.
5
Choose the appropriate documentation tool. Printed or PDF user manuals can be written with a word-processing program like Word or a sophisticated text editor like FrameMaker, depending on their length and complexity. Help files can be written with a help authoring tool like RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer.

Community Q&A

Question

Are there any free tools for software documentation?

Community Answer

Try Doxygen. You comment your code, run Doxygen, and you have a webpage. Add LaTeX, and you have a PDF.
Question

I have seen keypresses documented in multiple formats. Is there an actual standard for items or are they all different?

Community Answer

There is no universal standard; however, it is a good idea to set a standard for your own documents. For a couple of ideas, look at the Microsoft Manual of Style (available on Amazon) and the Apple Style Guide (help.apple.com/applestyleguide/). They have different styles, so if you write cross-platform documentation, you may end up using some elements from one guide and some from another.