Guidelines for writing software documentation

This article contains guidelines for producing high quality software documentation. Software documentation falls into a number of categories, including technical documentation and end user documentation.

Although standards exist for the creation of software documentation for specific industry sectors, there is no specific general software documentation standard as such. Many organisations, particularly larger organisations and consultancies will, however, tend to have their own internal documentation standards.

Technical software documentation should describe how an application functions. As such it can act as a reference manual for users such as developers, technical architects and designers concerned with the application's function.

What to document in technical documentation

For most applications, technical documentation can include information about some or all of the following:

• Files: A list of important files within the application.
• Functions and/or subroutines: Details of each function or subroutine, together with their parameters and return values.
• Global variables or constants: Details of what these are used for.
• How the application fits together: In the case of web applications using technlogies such as PHP or ASP it may describe which include files are used by which pages. It may also describe the modules or class libraries used by the application.
• 3rd party objects: In the case of applications using Microsoft technologies it may describe which 3rd party COM objects have been used.
• API Reference: Details of how to use the Application Programming Interface (API) if the particular application has one.
• Associated entities: It may also be useful to document related items such as the database used by a typical client-server application.

How to create technical documentation

Documenting software is often a laborious process. Thankfully it is possible to get utilities to help with the process. Due to the speed of automated documentation tools compared to the process of manually writing technical documentation, they can save considerable time and money.

Our range of software source code documentors can help with documenting Active Server Pages (ASP), Visual Basic 6.0, .NET Framework code (both VB.NET and C#), PHP and Microsoft SQL Server databases. A range of other documentation tools also exist for a wide range of other programming languages and development platforms. Code documentors will tend to parse application source code and compile documentation summarising key entities within the source code (e.g. functions, subroutines). Some source code documentors can create WIndows help files for application source code - often these are indexed and searchable which can be a considerable bonus when documenting large complex applications or those such as ASP web applications where the business logic may be spread over many pages and include files.

In order to manage the costs and time involved with the documentation of software, an alternative is to outsource the creation of an application's technical documentation. Dedicated technical writers will ensure that your technical documentation is of the highest possible standard, which is particularly important if your documentation is to be distributed outside of your organisation. Our software documentation portal lists a number of technical writers who may be interested in assisting with the documentation of your software. Don't forget that in many cases it may be worth considering just employing a technical writer to review the documentation to ensure it is legible and suited to its intended audience.

Improving technical documentation

Problems arise if the documentation is created independently of the application source code. At its worse, this can lead to inconsistencies between the application and its documentation, which can lead to problems and confusion at a later stage.

Keeping documentation synchronised with an application's source code is made easier if the application contains its documentation within the actual source code itself. Programming languages such as Java and the .NET Framework have official code documentation standards. In Java this is provided through the JavaDoc specification. The Microsoft .NET Framework supports the XML Comments system, which can be used to document C# [see Documenting C# source code with XML Comments] and (from version 2.0 of the .NET Framework onwards) VB.NET [see Documenting VB.NET source code with XML Comments].

Provided this in-line documentation is always updated as the source code is modified, this makes it possible to generate documentation for a specific version of an application. This raises the prospect of self documenting software, which can drastically cut the amount of time and effort required to maintain technical documentation.

Documenting database and application servers themselves is also possible in many cases. For example, Microsoft have enhanced the facilities for documenting SQL Server databases with the release of SQL Server 2005 (see Documenting a Microsoft SQL Server database).

End user documentation is intended for the actual users of the software application. It can take many forms, from online websites, to electronic reference guides such as Windows HTML Help as well as the more traditional printed documentation. Although end user documentation is normally prepared in a Word processor or HTML editor, various tools exist to assist with the creation of the documentation. Such tools include document conversion utilities, screenshot generators and annotators and online help compilers.

Check out our software documentation portal, which showcases a selection of end user documentation tools.