Overview
The preparation of documentation is an important stage in the process of software development and release. Not all companies pay enough attention to this stage. This careless approach to development has a negative impact on software maintenance and further evolution.
Documentation allows you to estimate the cost of development and coordinate the functionality of the future system. If there are disputes about the cost and timing of the development of a particular feature, the documentation can become a definite guarantee for the customer. If there is a need to improve the application, the documentation will facilitate the process of development and give a clear understanding of whether it is possible to integrate new functionality into the existing system.
What do we mean by software documentation?
Software documentation is a set of documents that describe in detail the technical characteristics and consumer qualities of the software, as well as provide information about the process of its development, application, and maintenance. These documents usually include manuals, user instructions, and guides, software reviews, specifications, testing procedures, etc.
Software documentation can be divided into 4 categories by its type:
- Design (architectural) documentation. It describes the main provisions, goals, tasks, and stages of the project, which are applied in the development of the software and its working environment. It is a general overview of the software, intended primarily for the specialists working on the project.
- Technical documentation. Sometimes absolutely all documentation for software is called technical, although it is not quite right. The technical documentation includes the description of the program code and functions, data structures, algorithms, APIs, and interfaces performed by it. Besides, it shows in detail the process of software development, the principle of its work, and the order of its operations.
Such materials are often provided with the source code of the program or are embedded in it in the form of comments. To simplify the creation and updating of technical documents, special templates are used or this is done automatically with the help of documentation generators (Javadoc, Doxygen, NDoc, etc.).
- User’s documentation. If the first two types of materials are targeted at specialists, this category is intended for software users. It does not contain complex technical descriptions of the code and the principles of its operation. User documentation focuses on describing the functions of the software and the rules of its operation. The most common formats for user documentation include the User’s Guide and the User’s Reference. It also often includes troubleshooting instructions and answers to frequently asked questions.
- Marketing documentation. Marketing materials help attract the attention of the target audience to the product and tell them about its functions, features, and benefits. As opposed to user documentation, marketing documentation is much shorter. It often consists of a single promotional booklet designed with a view to familiarizing the user with the program or application.
Who is responsible for preparing software documentation?
A technical writer develops technical documentation for software. This specialist prepares almost all kinds of such materials, including User’s Guide and User’s Reference, technical projects for specialists, marketing texts, etc.
Job duties of a technical writer:
- Design of technical documentation in accordance with internal (corporate), national or international standards.
- Keeping it up to date, making changes and additions to the documentation when the software is updated.
- Preparation of graphic and media materials (diagrams, charts, screenshots, video guides) according to the specified parameters and their inclusion in the technical documentation.
- Testing and analysis of new programs and applications, applying the experience and knowledge gained in the preparation of documentation.
- Collecting the necessary information about the software from all project participants: developers, managers, designers, testers, customers, etc.
- Translation of technical documentation into foreign languages, preparation of technical presentations, and participation in software implementation processes.
The difference between the technical documentation and the technical task.
The technical task and the technical documentation are two different documents. The technical task answers the question “What should be done?” and is written by the business analyst at the beginning of the project. The technical documentation is developed by the technical writer. This document is created after the technical task and answers the question “How should it be done?
What should quality documentation be like?
- Structured.
Having a clear structure is one of the most important requirements for software documentation. It must be logically organized into sections and subsections, and have paragraphs, lists, and other elements of text formatting. If we are talking about materials for users, text descriptions are not enough. Screenshots of the program in high quality are needed. Video materials can be developed, but they cannot fully replace text materials.
- Holistic.
All software documentation should be in a single format, including both project and technical documents for employees and materials for users. It should be in line with other documents issued by the company and follow a unified corporate style. A good solution is to standardize the process of preparing documentation to avoid discrepancies in the future.
- Informative.
Another important requirement for quality software documentation is that it should be clear and informative. To achieve this goal, it is necessary to strike a balance between the amount of data and the simplicity of its presentation. Both too little and too much information are bad options, especially when it comes to user documentation. On the one hand, it is not necessary to make it overly superficial and simplistic, and on the other hand, you shouldn’t overcomplicate the material.
- Relevant.
Good technical documentation should be designed for a specific target audience. Before preparing materials, it is necessary to determine the range of employees or customers for whom they will be useful and appropriate. It is also necessary to have an understanding of the level of expertise of the audience and what tasks and issues the documentation can address.
The benefits of having software documentation
The availability of technical documentation makes it possible to:
- More precisely and quickly estimate the cost of development and coordinate the functionality of the system.
If there is a need to upgrade the application, the documentation will facilitate the process of modernization and allow you to more accurately predict the cost of new functionality in the existing system.
- Reduce development time.
When developers join the project, they just see huge code with unclear architecture and try to understand how to work with it. Most of the work time is spent on contextual immersion: thoughtful inspection and study, rather than on development itself.
- Reduce development costs.
With technical documentation, developers quickly understand what they are working on and more easily can accept legacy systems. And in the absence of project documentation, a huge part of the budget will be spent on studying “how it works”, “what it is” and “why it is so”. And this is about 30% of the budget allocated for the project.
- Facilitate the process of code maintenance and improvement.
You will have a clear understanding of whether it is possible to integrate new functionality into the existing system.
- Reduce the risks inherent in the work of the team
When employees leave a company, they take with them the knowledge of the parts they did. Developing and maintaining obscure parts becomes very expensive – it is necessary to explore how it works now and to complete something new over the current behavior.
- Provide the possibility for users to solve their own application tasks with the help of the system.
The user documentation describes all functions of the software and how to use it. This allows people to quickly and easily navigate through the software.
Documentation helps to systematize disparate data, as well as creates a basis for effective management decisions.
You can also read a case study from our practice: Development of technical documentation for the existing software.
