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.
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.
This portal showcases a range of software source code documentors that can help with documenting C++, Java Active Server Pages (ASP), Visual Basic 6.0, the .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. This website lists 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 your technical documentation
Problems arise if the documentation is created separately to the application's 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) Visual Basic.NET [see Documenting Visual Basic.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 Microsoft SQL Server databases).