Writing Software Documentation
This article describes what documentation you should consider writing for your software
products, and how to go about producing the different types of documentation.
Documentation for Installation (ReadMe's)
Most software is supplied with a text or HTML based file that explains how to install
the software. Typically the file is called something readme.txt or ReadMeFirst.html.
Common inclusions within a readme file are:
- System requirements for the new software. Include details of operating system required,
plus and specific hardware or software requirements. Software prerequisites such as
database drivers or 3rd party components are useful to know about.
- Information about how to install and uninstall the software.
- A "quick start" guide describing how to get the software up and running as
quickly as possible.
- Contact details of the organisation releasing the software.
- If a trial version, how to upgrade to the full version.
Technical 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.
- Methods and properties: 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
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.
HTML Help files allow application help to be compiled into a single, searchable .chm file.
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.
Many software packages on the Microsoft Windows platform offer help in Microsoft's HTML
Help format. This help format is familiar for end users, and offers a number of useful
features including tables of contents and search facilities. Being contained within a
single compressed .chm file also makes it straightforward to distribute help with
applications.
Basic HTML Help files can be created using Microsoft's HTML Help Workshop utility.
There are a also number of commercial packages available that assist with creating more
sophisticated help files.
As well as compiling the end user documentation into a help file to distribute the help
with a software application, it is also increasingly common for help to be made available
via a website. Obviously this is an inconvenience to users who do not immediately have
access available to the Internet. However, it makes it more straightforward for the
software vendor to update the documentation. It may also help with product marketing as
the documentation will be accessible for search engines to incorporate in their search
catalogs.
It also makes interactive documentation a possibility...
Interactive Documentation
There is an additional class of software documentation - documentation that is
interactive in nature. This is commonly achieved by the end users of the software being
able to contribute to the documentation. It may take the form of:
- User discussion and support forums.
- Wikis.
- Blogs.
The advantages of interactive documentation are that users can assist each other and
knowledgable users can help to contribute to the documentation. Interactive documentation
can also assist the software vendor by cutting support costs, and allow the product
development team to gain ideas for future product enhancements.
|
