What is software documentation?
Software documentation is the information that describes a software product to the people who develop, implement and use it. It includes the technical manuals and online material.
Software documentation shows:
- what the software developers did when creating the software
- what IT staff and users must do when starting it up and using it
Why do you need documentation?
Software documentation provides information about a software program for everyone involved with the application. Documentation records the development process and helps with tasks such as installation and troubleshooting.
Advantages of good documentation:
- Keeps track of all parts of a software or program
- Maintenance is easier because maintenance engineers have an information source
- People other than the developer can understand all aspects of the software
- Helps user training
- Ensures knowledge de-centralization by making system knowledge available for present and future users.
Good documentation helps users get to know the software and what it can do. If the documentation is effective, users are more likely to support the use of the software and will probably use it more readily. With informative documentation less time is lost searching for answers to initial problems and users can find solutions without needing to call on technical support.
The documents associated with a software project may also be essential evidence for system certification.
Examples of software documentation
Some examples of software documentation include the following:
- System documentation: such as architectural diagrams showing the structure of the software and its technical design.
- Application programming interface (API) documentation: reference documentation for calling APIs. It establishes standards for API communication and ensures that different APIs work smoothly together.
- README files: a high-level representation of software that usually comes with the source code.
- Release notes: review the new features and bug fixes included in each release of a software program.
- How-to guides: show IT staff or end users how to deploy or use the software.
- Tutorials: often in video format, show how to use the software or a specific feature.
- Reference documents: provide IT and end users with technical documentation of the software.
- Explanations: explain a specific elements of the software for the user.
The overall documentation for the finished software product is called product documentation. There are two types of product documentation:
- System documentation – for the people, such as engineers, who will be responsible for maintaining the system.
- User documentation – for the people who will be using the software
One of the Agile manifesto values is “working software over comprehensive documentation”, suggesting producing code is more important than creating a lot of system documentation.
Is detailed system documentation really necessary?
System documentation is a written reference of how the software works. It’s important for trouble shooting and possible further development. Without it, people don’t know how the system is put together or why aspects of it behave in a certain way.
System documentation
System documentation includes all the documents that describe the system. To understand and maintain a system, it’s helpful to have documents that describe the design, implementation and testing of the system.
For a large system you should provide:
- Requirements documents and rationale which give information about system functionality and what it should do. It should outline the product’s purpose, its features, functionalities, and behaviour.
- Description of the system architecture that describes the main architectural decisions.
- Description of the architecture of each program.
- Description of the functionality and interfaces for every component in the system.
- List of program source codes with comments where necessary. Source code documents may include the following details:
- HTML generation framework and other frameworks applied
- Type of data binding
- Design pattern with examples (e.g. model-view-controller)
- Security measures
- Other patterns and principles
- Validation or quality assurance documents.
- System maintenance guide - this document should detail known problems with the system and provide solutions. It also should represent the dependencies between different parts of the system.
For smaller systems system documentation is not as comprehensive. A minimum range of documents for smaller systems should be:
- A system specification
- An architectural design document
- The program source code.
Document management
During the development stages it can be hard to make sure the documentation that will eventually form your end product system documentation remains updated. It is easy to get caught up in creating the system and forget to modify original documents with changes that you make as the system develops. However, if you don’t keep updating your documents, the documents that you supply with the end product won’t be accurate.
It’s helpful to have a document management system that records document relationships. A good solution is to use software tools that record document relationships and remind software engineers when changes to one document affect another. There are several of these kinds of products around. If the documentation describing the system is out of date or wrong, this will cause problems down the line for the end user or implementer.
User documentation
As you can imagine, there are different levels of users. To write good user documentation you need to understand who your users are so that you can create documents that are useful to all users, regardless of their level of expertise. You also need to distinguish between end users and system administrators.
- End users use the product for a purpose, they aren’t interested in how the software works, they just want to know how to make it do what they want it to do.
- System administrators have to manage the software so that end users can use it in the way they need to.
It can be hard to create a document that is comprehensive and can be used effectively by all levels of users. One solution is to create several different documents as demonstrated in the diagram below, or these could all be sections of the same document.
How these documents are used
The functional system description provides an overview of the system. It should summarise the system requirements and briefly describe the services provided. Users should be able to read this document with an introductory manual and decide if the system is what they need.
The system installation document is aimed at system administrators and should contain details of how to install the system. There should be a description of the files included in the system and the minimal hardware configuration needed. It’s also necessary to describe the permanent files which must be established, how to start the system and the configuration dependent files which need to be changed to adapt the system to a specific host system. Although installation often happens automatically, this document is still useful to help system managers find and fix any installation problems.
The introductory manual is usually an informal introduction to the system. It describes the “normal” functioning of the system. It should also describe how to get started and how end-users can use common system facilities. There should be a lot of examples.
The system reference manual describes the system facilities and their usage. It gives a complete list of error messages and should describe how to recover from detected errors. It must be complete. While it’s good if it’s well written, the most important aspect of this manual is that it’s a fully complete description of the system.
Some types of system, for example command and control systems, should also have a more general system administrator’s guide. This guide should describe the messages generated when the system interacts with other systems and how to react to these messages. If system hardware is involved, it might also explain how the operator should maintain that hardware. For example, it might describe how to add new hardware to the system or diagnose hardware faults.
As well as these documents, which can be quite long, many applications provide quick reference guides with the most essential information.
Online documentation
Online end-user documentation can include multi-media formats for much of this information, and should include the following sections:
- FAQs
- Video tutorials
- Embedded assistance
- Support Portals
Isn’t it better to put everything in online videos?
You have probably used software that only has online help tutorials instead of a manual. These are useful but there are still good reasons for supplying a thorough user manual.
Online tutorials are often split into sections that users need help with rather than a step by step guide. The problem with that is new users may not know exactly what they need help with and can spend time looking around the online tutorials without knowing what to look at to help them use the software. Manuals provide a very good general overview and can be online or in hard copy, depending on size and, in some cases, user preference.
Most software engineers find it easier to develop good programs than to develop quality documentation. However, it’s equally as important. There’s no point in having a great product if people are unclear about how to use it or how to maintain it! Computer software documentation is often badly written, out of date or incomplete. How can you create documentation that is clear and useful?
Structure
A well planned structure makes a document readable and relevant information is easy to find. The following table gives a suggested structure for documents:
| Information type | Description |
|---|---|
| Identification data | Clear title that identifies the document including date and any copyright information. |
| Table of contents | Section titles and page numbers. Have consistent naming and numbering of chapters and sections. |
| List of illustrations and diagrams | Identified with figure numbers |
| Introduction | Gives purpose of document and brief summary |
| How to use document | Advice for most efficient use of document |
| Concept of operations | Conceptual background to use of the software |
| Procedures | Directions on how to use the software |
| Information on software commands | Description of the commands the software supports |
| Error messages and problem resolutions | The errors that will be reported and what to do to recover from them |
| Glossary | Definition of any specialised terms that have been used, including acronyms. |
| Index | List of key terms and relevant page numbers. This makes the document much more usable. |
| Search capability | If the document is electronic, a way to find key information through searching |
Not all documents will need all of these elements but this provides a good structure to work from.
Developing a comprehensive structure is a good start, but then you need to make sure the content within that structure is well written and the information is relevant and appropriate.
What does a well written document look like? What are the essential features of good writing in a software document?
Listen to a technical writer for Google, Beth Aitman, give what she considers to be the five key points about writing effective documentation by watching the video Writing effective documentation| Beth Aitman (LeadDev, 2017).
Did any of those five points surprise you? Those five points provide a good overall approach to creating a document that will be useful and readable. When you code, you are careful, revise often and have a series of checks as you try to create the best version of a program. Creating a document should follow the same process as it is just as important.
Style does matter because you want people to be able to follow the information. It’s a lot of work creating documentation, so it’s worth putting in enough time to ensure that the finished document is useful and easy to navigate. Let’s look at some good rules that will help you produce a well written document.
| Good writing practices | |
|---|---|
| Use active verbs | "When you use the arrows, it takes the system…" is better than "When the arrows are used, the system is taken…" |
| Shorter sentences are better | Break up your information into short sentences rather than one long sentence with lots of different information. |
| Keep paragraphs short | Short paragraphs help the reader retain information. |
| Be precise | Define any complex terms you use. |
| Use headings, sub-headings and lists | Sections make text easier to follow, lists make facts clearer and easier to recall. |
| Keep the reader in mind | Write at a level appropriate for the reader, and explain complex things in a different way to aid understanding. |
These are style rules that can help. Using a grammar and spell check improves the document and always get someone else to go through it to check it and suggest improvements, just as you would a page of code.
This section below, taken from an actual user manual but with the product name changed, could definitely be improved. Try re-writing and re-formatting it, using some of the style suggestions we have mentioned. Then compare it with one we wrote which is in the feedback section.
There should always be at least two copies opened of your KPP database: 1) the “master” databasewhich is the working database you open in KPP and 2) a “backup” database in which are included your most recent edits. Your backup database should be saved on a different computer than your work computer – preferably a computer in a remote location for example something like network server.Every time your KPP database is modified, such as when data is entered or edited, a backup copy of your database should be saved. You do this by following these steps:
Open Windows Explorer or My Computer and navigate to the folder where your KPP masterdatabase is saved. Right-click on the database filename (it will have an .sdf extension). Select Copy. Right click in the same folder and select Paste. This will create a backup database with the name databasename – Copy. sdf (e.g., MyDatabase – Copy. sdf). Next, rename the backup. Right-click on the backup database filename and select Rename. Modify the database name to include the date (e.g., MyDatabase – Copy – Oct012022) and hit the Enter key.
This is how we would change it. Can you see how it looks much more readable with the text more spread out and in numbered lists? It’s easy for a reader to skim the list searching for the information they need. We also changed all the verbs in the first paragraph to be active verbs so that it reads more easily. The sentences are clearer as well as being quicker to read. You may have made some other changes.
You should always have at least two copies of your KPP database:
- the “master” database which is the working database you open in KPP
- a “backup” database that includes your most recent edits. Save your backup database on a different computer to your work computer – preferably a computer in a remote location such as a network server.
Every time you modify your KPP database, such as when entering or editing data, you should create and save a backup copy of your database. You can do this by following these steps:
- Open Windows Explorer or My Computer and navigate to the folder where your KPP master database is saved.
- Right-click on the database filename (it will have an .sdf extension).
- Select Copy.
- Right click in the same folder and select Paste. This will create a backup database with the name databasename – Copy. sdf (e.g., MyDatabase – Copy. sdf).
- Next, rename the backup. Right-click on the backup database filename and select Rename.
- Modify the database name to include the date (e.g., MyDatabase – Copy – Oct012022) and hit the Enter key.
Have a look at this page from a software user manual. Don’t worry about reading the text, what do you notice, visually?
- There are only short sections of text
- Screenshots are used for visual explanation
- Bolded text is used for emphasis
Using screenshots and other visual aids make instructions and user steps very clear. They are more effective than a lot of explainer text.
When explaining steps in a process and using screenshots of the software, consider using simplified graphics. This means, for example, in a menu list, block out all items in the menu, except the item you want to discuss. This cuts back on visual complexity and helps the reader focus on the key information.
Using icons can add consistency to documentation and help the user to search out specific information. They can also help you break up the text into shorter, more concise sections.
Documentation standards act as a basis for document quality assurance. Documents produced according to appropriate standards have a consistent appearance, structure and quality. One standard used for software documentation is the IEEE standard which specifies the documents required (IEEE stands for Institute of Electronics and Electrical Engineers).
Other standards that may be used in the documentation process are:
- Process standards: define the process that should be followed for high-quality document production.
This includes the quality assurance process you need to follow to make sure the documents are at industry standard and software tools to use to keep the documents at standard. The acceptable document quality aimed for will depend on its purpose and the reader. - Product standards: define the documents themselves e.g. their organisation and structure. This standard applies to all documents and includes identification, structure, presentation standard and update standard. Things such as fonts, page numbering, headings are identified here so that all documents are consistent and therefore easy to follow and access.
Although some of the documents are used during the development process, when preparing them for end product documentation they need to focus on what the document reader needs to know so may need extra editing. - Interchange standards: ensure that all electronic copies of documents are compatible.
You need to choose the appropriate standard that suits a particular project, and modify it if necessary. Small projects developing systems with a short lifetime need different standards from large software projects where the software may have to be maintained for 10 or more years.
The IEEE standard
This standard for documentation started in 1987 and has since been revised, mostly recently in 2012. It details the content that should be in user documentation and also suggests formatting standards. The IEEE standards have good advice for writing documentation and if you’re interested in more detail have a look at their website.
Critique end-user documentation
Find 2 or 3 sources of product documentation, either online or in manual form. Look through each one of them critically.
- How is it structured?
- How do they use visual information?
- Is the language easy to understand? If it is, what makes it easy?
- Does the information seem comprehensive?
- Is the system fully explained?
- Is there system documentation and user documentation?
- Does the documentation cater for different levels of user?
Reflection
What would you find most difficult about creating product documentation?
If you know that you are not very good at writing explanations or instructions, work on improving your skills. Write a set of instructions on how to log into this learning system. Aim for a reader who has never used a Learning Management System before and break down each step. Ask someone you know (not on the course) to follow the instructions and see if they can. If they can’t, refine the instructions until they can.
Keeping language simple and clear is a skill that takes practice.
Documentation may seem like the least important part of software engineering but for users who buy your products it will be a key element. Without good, thorough, readable documentation all those great features that you developed might remain completely inaccessible.
