Technical Documentation – What Is It, What Should It Be And Who Creates It?
Preparing software documentation is a very important step in the software development and release process. Unfortunately, not all companies pay enough attention to it, which negatively affects both the maintenance and development of the software, and the interaction with its users.
Content:
1. What is technical documentation for software? Its types and formats
2. What quality documentation should be?
3. What are terms of reference and technical design?
4. Who is a technical writer? Features, tasks and problems of this profession
5. Summing up
In our new article, we will talk about the benefits of competent technical documentation. You will learn what kind of documentation is considered to be of high quality and what it should include, what types and formats of such materials exist and how they differ from each other. In addition, we will tell you about the profession of a technical writer, what they should be able to do and what is the current situation on the market for these specialists.
What is software technical documentation? Its types and formats
Software documentation is a set of documents that describe in detail the technical characteristics and consumer qualities of software, as well as information about the process of its development, application and maintenance.
The software documentation package includes not only technical materials, but also many other types of documents. These include manuals, user guides and help, software reviews, specifications, test procedures, and more. For ease of classification, all of this documentation is divided into 4 categories:
- Design (architectural). Describes the fundamentals, goals, objectives, and project stages that are used to create software and its work environment. It is a general overview of the software, intended primarily for specialists working on a project.
- Technical. Sometimes absolutely all documentation for software is called technical, although this is not entirely true. Directly technical documentation includes a description of the program code and the functions it performs, data structures, algorithms, APIs and interfaces. In addition, it displays in detail the software development process, the principle of its operation and the operating procedure. Often such materials are supplied 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, they use special templates or do it automatically using documentation generators (Javadoc, Doxygen, NDoc, etc.).
- Custom. If the first two types of materials are focused on specialists, then this category is intended for software users. It does not contain complex technical descriptions of the code and how it works; instead, it focuses on describing the functions of the software and the rules for its operation. The most common user documentation formats include the User's Guide and the User's Reference. It also often contains instructions for solving problems and answers to frequently asked questions.
- Marketing. Another of the main types of software documentation is marketing materials that help to attract the attention of the target audience to the product, tell about its purpose, capabilities and benefits. Unlike custom marketing, marketing documentation is much more concise. It often consists of a single advertising brochure designed to familiarize the user with a program or application.
What quality documentation should be?
First of all, it must comply with a certain set of standards. Namely, such as:
- Structuredness. Having a clear structure is one of the most important requirements for technical documentation. It should be logically organized into sections and subsections, with paragraphs, lists, and other text formatting elements. If we are talking about user manuals, then just a text description is not enough here - it needs to be supplemented with high quality screenshots of the program. No less popular are video manuals, which, however, cannot completely replace text materials.
- Uniformity. All software documentation should be in a single format, including both design and technical documents for employees and materials for users. In addition, in the course of drafting it, you should check with other documents issued by your company in order to adhere to a uniform corporate style. It will also be useful to standardize in advance the process of preparing the documentation in order to avoid any discrepancies in the future.
- Informativeness. Another important sign of high-quality software documentation is its clarity and information content. To achieve this goal, you need to be able to strike a balance between the amount of data and the simplicity of their presentation. Both a lack of information and an excess of information can worsen this indicator, especially when it comes to user documentation. On the one hand, it is not necessary to make it too superficial and simplified, and on the other hand, excessive complication of the material should not be allowed.
- Relevance. It is imperative that good technical documentation is aimed at a specific target audience. Creating a common, one-size-fits-all guide for developers and users is an interesting but difficult task that even an experienced technical writer is unlikely to be able to accomplish. Before developing materials, it is advisable to determine the circle of employees or clients for whom they will be most useful and interesting. It is also necessary to have an idea of the level of preparation of the audience and what its tasks and problems can be solved by this documentation.
What are terms of reference and technical design?
Typically, all technical documentation does not need to be written prior to software development. Most often, modern IT projects are created according to the Agile methodology, and work on them is carried out in sprints, which allows you to write documentation in parallel with the development process.
However, there are several documents that ideally should be prepared before the start of software development: these include the terms of reference (TOR) and the technical project (TP).
The Terms of Reference is a key preliminary document, it provides a general description and purpose of the program, its business goals, the expected scope of work, as well as the order of the stages of development, evaluation and acceptance of the software. The TOR is drawn up by a business analyst after negotiations with the customer, therefore, it is necessary to accurately and in detail record all his requirements and the vision of the future program. If necessary, it is also discussed with the members of the project executing team: developers, designers, project managers, etc. In fact, this is a statement of the problem expressed in a documentary form.
After drawing up and agreeing on the terms of reference, work begins on a technical project, which is already being prepared by a technical writer, not a business analyst. TP is a set of materials that describes the architecture, scenarios, methods, approaches, technical solutions and other data used in the development of the program. For example, in a technical project, they display the structure of servers and databases, interface layouts, descriptions of algorithms and integrations with external systems or equipment, user scripts, etc.
In simple terms, if the technical assignment answers the question "what needs to be done?", Then the technical project - the question "how to do it?"
Who is a tech writer? Features, tasks and problems of this profession
The development of technical documentation for software is carried out by a technical writer. He prepares almost all kinds of such materials, including manuals and guides for users, technical projects for specialists, marketing texts, etc. The duties of a technical writer include:
- Registration of technical documentation in accordance with internal (corporate), state or international standards.
- Making changes and additions to the documentation as the software is updated, keeping it up to date.
- Preparation of graphic and media materials (diagrams, graphs, screenshots, video guides) according to the specified parameters and their inclusion in the technical documentation.
- Testing and analysis of new programs and applications, application of the gained experience and knowledge 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, participation in software implementation processes.
Ideally, a professional technical writer is a humanities student with a technical education who understands the basics of IT development, owns specialized terminology, knows some programming and markup languages, as well as automation tools for documenting processes. At the same time, he must have certain philological skills in order to compose technical material in a concise, informative and understandable way for both specialists and ordinary users.
However, such versatility and multitasking is available to few, so IT companies often complain about the difficulty of finding a good technical writer. On the one hand, its developers will tell the best about software, but they do not know how to present the program succinctly and understandably for a layman. And professional authors of texts, as a rule, do not understand programming, therefore they cannot accurately and informatively describe the structure, functions and other technical nuances of software.
Summing up
Software documentation includes 4 main types of materials: design, technical, custom and marketing. It can be drawn up in parallel with the development of software; in advance, you only need to prepare a technical assignment and a technical project. High-quality documentation must necessarily have a clear structure, be drawn up in a single format, be understandable and informative for both specialists and users.
In addition, the most important property of technical documentation is its compliance with the requests and needs of the target audience. The technical documentation is written by a separate specialist - a technical writer. He must not only write and edit the relevant texts, but also prepare graphics, videos and presentations, collect information about software, translate documentation into foreign languages, test and analyze programs and applications.
Apix-Drive is a simple and effective system connector that will help you automate routine tasks and optimize business processes. You will be able to save time and money, direct these resources to more important goals. Test ApiX-Drive and make sure that this tool will unload your employees and after 5 minutes of settings your business will start working faster.