This article was updated on October 12, 2022.
The importance of documentation in software development is very easy to underestimate, but it can be a critical mistake for a project or even an entire company. However, the role of properly written and maintained documentation throughout the software development lifecycle is essential for all parties, from the company and its developers to customers and end users. It explains all the features of a project, informs us how we can work with them, helps to understand the project's functionality, and allows us to reduce onboarding time and costs.
Today we cover what software documentation is, what types there are, and why documentation is important in software development. We'll share industry best practices, approaches, and tools for documentation. Also, we will talk about Single Source of Truth (SSoT), which is impossible without quality software documentation, but highly important to carry comprehensive information about everything that happens in a company and its projects, making this information most accessible and usable for all participants.
Importance of Single Source of Truth (SSoT)
Let's start with the concept of why there is so much attention paid to properly compiling and maintaining documentation and why having it can create a system that helps the entire company work much better.
A Single Source of Truth (SSoT) is a set of comprehensive and organized information about all projects, processes, approaches, standards, and tools of the company, which helps company members to have a universal reference point applicable to the work of all departments and any company projects.
Accordingly, without quality SDLC documentation, such SSoT will largely be very cursory and exclusively recommendatory rather than comprehensive information that gives a complete picture and a set of specific practices that bring tangible results.
What can SSoT include?
The set and order of available information in SSoT can be different from company to company because there is no single standard for it. Companies creating SSoT can include a completely different set of processes, practices, and other things. Nevertheless, let's outline the most important things which can be a part of SSoT for an IT company with high-quality SDLC documentation.
Software development
It can include information from software engineering documentation, such as practices and standards for development processes, references to the resources and tools used in the development, architecture, and functionality of a particular project, contacts, and descriptions of its members, etc. Obviously, having all this information in one place and in an organized form available to everyone who needs it makes the development process much more consistent.
Regulatory compliance
Also, it can include information about the passing of external audits, negotiations with customers, or any other interactions that need to be fixed. When all the records, references, and reports about it are stored in one place, it is much easier to follow it, and it is much easier to come back to it and use it for further communication.
Search engines
Of course, in addition to carefully selected and organized information, a quality search engine should allow you to do this by titles, members, tags, and all other markers, which help you find the necessary information quickly. In this case, your SSoT becomes not only infinitely valuable for work but also highly usable.
For example, we at Mad Devs build our SSoT from the company's foundation, constantly adding and improving our Confluence, providing employees with everything they need for productive work and transparent communication. Also, we share the best standards, proven practices, and advanced tools with the world in our eBooks to help anyone who wants to improve their product, company, or an entire industry.
What is SDLC documentation?
Well, let's move on to the documentation itself. The software development documentation is a constantly updated set of documents accompanying the project and describing everything that this project is and what happens during its development. But how to write documentation for a software project in the best way? Here we need to start at the beginning and discuss two main approaches to creating and maintaining documentation.
What are the best practices for creating software documentation?
Since documentation is directly related to product development, the main approaches to documentation are based mainly on known project development approaches. Here, you should choose the approach you already use in product development to align the product and documentation work closely.
The waterfall approach to creating software documentation
The waterfall approach offers the clearest definition and description of all the goals, objectives, features, and, most importantly, the relevant processes in the project in advance and rarely includes later changes. This approach can be great for developing rather typical projects and helps to determine the budget and deadlines most accurately.
But software development is highly dynamic. And the more responsive the development approach is, the faster it reacts to changes in the technological or commercial market, so the more sustainable and profitable the final product is. That is why more and more companies, in most cases, choose the Agile approach to documentation and project development.
However, there are different companies for which the strictest timing and budgeting is the only appropriate option. Some companies and projects need strict planning, but not in all aspects. So there are proven approaches for all of them, and we highly recommend that you check out our article on this topic.
The agile approach to creating software documentation
The Agile approach in software development, and documentation, in particular, does not require creating exhaustive and complete documentation at the start of the project. Instead, the Agile approach offers the creation of documentation based on iterations of project development, representing only the actual project state and points.
All this allows you to save project resources from the beginning, maintain project development flexibility, and keep the documentation most relevant.
What are the types of software documentation?
The design of software documentation may differ from company to company and from project to project. Still, it is right to divide it into two main types, specifically business process and product documentation.
What is business process documentation?
Business process documentation is a set of documents representing all the information about the project development process, such as the project plan, schedules and reports, development standards and meeting protocols, comments of the project managers, developers, customers, and so on.
What is product documentation?
Product documentation, in turn, can be divided into several types.
The system documentation describes all product details, such as functional and behavioral requirements, architecture and design, source code, launching guide, testing, and support for the product. It can be designed as a set of separate documents or as a single document with different chapters and sections, depending on the company and the project.
User documentation may provide the information from the system documentation but redesigned for different usage scenarios, such as system administrators or end users. It may include an installation guide, troubleshooting guide, reference guide, and user tutorials and manuals.
At Mad Devs, we use two process documentation forms, one of which helps us to present the development process in the most detailed and clear way, and the other helps to regulate software engineering standards to ensure the best quality code.
Flowcharts
A Flowchart is a graphical representation of separate steps in sequential order. We use it as a program-planning tool to visualize what is going on and to help to understand the process. A flowchart might also show some flaws and bottlenecks in the process.
Flowcharts help us to:
- More clearly communicate the system's logic
- Make the debugging process easier
- Make the program analysis simpler
- Provide better documentation.
While they also have some drawbacks, for example, it isn't easy to draw a flowchart for complex processes, and flowcharts are useful when we need to visualize the process.
Programming Style Guide
We use programming style guides to ensure code uniformity. When we work on a product, the product code shall look as if it was written by one person. Even if there are many developers working on it, the code shall be uniform.
A programming style guide eliminates the need to guess about the style or, for example, how to name a variable. You simply follow predetermined rules. Coding documentation allows for more streamlined code creation and maintenance.
What do we include in a coding style guide? Whatever is related to code: indentation, vertical alignment, variable naming, comments; to eliminate any possibility of confusion, we also include such details as folder naming, asset naming, etc.
Checking hundreds or thousands of lines of code for compliance with style guides manually is difficult, if not impossible. That's why we use linters to ensure the code complies with the accepted coding style.
Linters are tools used to analyze the code for flaws, errors, stylistic errors, bugs, and suspicious constructs. Just some benefits that we get from using these tools are the following.
- Linters make code look like written by one person.
We like having a project code database that looks like it was written by one person. It also simplifies code maintainability, prevents bugs, and reduces the time to market of new functionalities. - They provide visibility of the codebase health.
We use the practice of adding a step in our CI/CD pipeline to measure the code health status. As soon as your code health deteriorates, you can notice it and take measures asap. - They increase the ownership over the code quality.
Senior developers know how the code shall look and function. If there are deviations, they can propose changes to improve the code quality. However, this is not the case with inexperienced developers. Not every developer knows how to detect whether the code is of high or low quality. A linter can tell automatically when the code quality drops, and the team can make the needed changes asap. It makes the entire team take responsibility for the code. - They help to control technical debt.
There are many more advanced linters that help to control technical debt. They detect issues such as style guide mismatches, poorly designed code, or code flaws, and make technical debt explicit. For example, for Go, we use ktlink, Gofmt, and detekt to manage technical debt.
There are a lot of linters for different programming languages, software integrations, and configuration files. Any check that can be automated and that we need can be turned into a linter. We can also write our own linters even though it is not a common practice in our company because there are too many of them already. All in all, linters help us to save time, money, and productivity.
And also, in Mad Dev's we use product document README, in which we reflect in detail all the information about it
README
README is our main product document. We can compare it with a description of a product: all information about the product is presented in an understandable way. If there is no description, a developer might spend too much time trying to understand what project it is and how it shall be used.
A README document is not just a mere description though. It is a document created to help us to use the repository content without external assistance. When writing a README document, we:
- Inform the reader about the repository content.
- Create a resource that allows the onboarding of a new specialist faster and cheaper.
- Provide our client with an opportunity to check what the repository is for.
- Enable developers to start working on the project after a long break without any reverse-engineering procedures.
README components
The structure of our README documents is not fixed because the project components and resources might differ. Also, we write a README document in stages. While working on a project, we are completing its README.
For example, the How to Run Tests section can be written later when the code is covered in tests and similar. Usually, we include the following sections in a README document.
- Name - the repository name. A self-explanatory name is better. For example, if you see the name AWS-ESK Base, you aren't going to wonder what the project is about.
- Description - here, we indicate the repository content, the project (if the repository is a part of a bigger project), and why the repository resources might be useful for you. If we move on with Ansible, its description tells you everything about the repository:
- Technologies - here, we list and describe the technologies used in the repository, for example:
Apollo
Apollo Server 2.0
GraphQL - Prerequisites - in this section, we list and provide links to external resources, utilities, and modules that are required to make the repository resources function.
- Folder structure - we describe the folder structure and its content.
- How to Run - it is one of the most important sections in a README document. It explains how you can work with the repository content. For example, if it is code, this section explains how to run it on your computer. Here, we mention the mode in which it can be run:
Developer mode
Testing mode
Production mode.
For Docker projects, we provide launch commands. - How to run tests - every repository contains tests, and README explains how to launch them.
- How to deploy on production - if the resources shall be deployed in production, we explain how to do it, describe how they interact with external services, and explain how to set up the environment and external services such as HTTP Proxy and similar.
- Configuration files - here, we describe all configuration files needed for the project launch.
- Variables - in this block, we describe all variables that can have an impact on the service. Then, we move on with variables. If the variables are in an environment, we start with the environment.
- Launch parameters - if there are launch parameters, we describe them, too.
- Extended documentation - if there is a landing page or extended documentation, we provide links to them.
- Mockups - here, we provide links to design mockups, sketches, a PSD file, and an interface, if any.
README formatting
What about formatting? We make it simple: we apply special formatting for:
- Code
- Console commands
- Variables description.
It is worth remembering that your README doesn't sell your work. It explains how your product works, how it can be used, and what problems it solves. It shall enable developers to understand everything about your project without delving into code. Once your document complies with these requirements, we can call it successful.
How to properly maintain software documentation?
In addition to knowing all kinds of necessary software documentation and using the most appropriate approaches to maintaining it, you need to ensure that you act in accordance with all of this. So now we will tell you how to detect outliers in advance, and give you practical advice for preventing them.
Red flags of poor software documentation
One may wonder, how do you know if software documentation is not at the desired level of quality before it actually holds up your project onboarding, slows development speed, or gets negative feedback from your stakeholders? Let's try to identify the main red flags in software documentation. The programming documentation is likely to be of poor quality if:
- The documentation does not have a separate repository or any other tool or platform properly structured and accessible to all project participants.
- The documentation does not have a separate regular task in the project management system, with clearly defined responsibilities and strictly defined regular deadlines.
- There are no clear standards for documentation, quality assessment points, and actuality checks.
- The documentation is maintained by only a few team members instead of each direct participant.
- If you do not have a technical writer, the documentation remains difficult for everyone who needs it.
What are software documentation requirements?
Here are some essential requirements and ready solutions you can safely practice to ensure compliance with industry best practices and standards, getting the most out of them and making your documentation the highest quality.
Write the documentation in the necessary scope and detail
There should be enough of everything. While striving to ensure that your document contains what is necessary only, you should not omit details that may be important to customers, developers, or users. At the same time, to provide each of them with comprehensive information, you need to ensure that it is not excessive and does not take more time to study than necessary.
The same applies not only to its scope but also to its form. The documentation should not use excessively complex or specific wording so that those who use it will immediately get the information they need rather than being challenged to get it. At the same time, the wording should be carefully chosen and structured to capture the subject matter most accurately.
Use graphics and links
Information provided in a visual format is much faster and better understood by most people. If the type of document, item, or process allows you to capture it graphically, you can present it in a way that is much more meaningful and understandable to anyone reading the documentation, regardless of their technical or business background.
Also, use hyperlinks to provide the ability to quickly find the information needed for further study without having to go beyond the documentation. This way, the documentation reader is not interrupted while studying it, and it is much quicker and easier to get the information they need.
Documentation is a team effort
Documentation includes the work of very different departments, from developers and designers to analysts and marketers. If a person who works in only one of them is going to collect and write out the work results, most likely, the documentation will not include everything you need in a proper form.
Therefore, all documentation units should come from those directly involved in a particular part of the product. Then the documentation will provide the most complete and accurate information in every aspect.
And also, a technical writer with good technical knowledge and word processing skills is needed to make the final documentation not only comprehensive but also the easiest to learn and use.
Documentation should be up-to-date
Documentation should keep pace with the processes or products and always represent their most actual current state. If this is not done, such documentation simply loses its meaning and does not help speed up the development process, simplify the work with the product, etc.
In order to keep the documentation up-to-date, its updating needs to be the same task as the development of the product itself and needs to take place on schedule. You can also use version control for the documentation, as for the product itself, to greatly simplify its management and creation.
How to choose a software documentation tool
The choice of a Software Documentation Tool depends largely on what tools a company already uses, what kind of integration options they provide, and how extensive its documentation capabilities are. Here, we list the top tools, many of which we successfully use ourselves.
Atlassian Confluence is an incredibly powerful and multifunctional project collaboration platform. It integrates perfectly with Jira, and if you are running your projects in it, Atlassian Confluence is ideal for creating and managing documentation with the ability to use the wiki system and user stories.
Document 360 is a separate platform focused on creating a knowledge base for documenting software development, giving you many options for creating, managing, and maintaining it.
Bit.ai is a tool for collaborative, interactive work on documentation with the ability to submit code directly to it, provide links to code and other documents using a wiki system, and export all of it as a detailed PDF document.
GitHub / GitLab, these version control systems can be great not only for code but also for documentation, with the possibility of using a wiki system providing internal links to each other, as well as uploading documentation as web pages.
Bottom Line
As you can see, documentation is not limited to reports only. We create documentation at all stages of the development process. It helps us to write code consistently, ensure code quality, and make the entire process more understandable.
