In the fast-paced world of software development, it’s easy to overlook the importance of documentation. Many developers view it as a tedious and time-consuming task, but the truth is, documentation is critical to the success of any project.
If you want to build great digital products, your documentation needs to follow suit. Without proper documentation, projects can quickly spiral out of control, leading to missed deadlines, increased costs, and frustrated stakeholders.
In this article we take you through the most common types of documentation, explain how taking the time to document your work actually saves time and money in the long run, and provide tips for mastering the art of documentation writing. Should you lean on AI assistants for help? We tackle that question too.
Let’s get documenting.
Documentation doesn’t have to be a chore
Many developers view documentation as a chore, something that takes away from the more exciting and challenging work of writing code. They may feel that documentation is a distraction from the creative and technical aspects of software development, or that it doesn’t directly contribute to the functionality of the software. However, this mindset is short-sighted and ultimately leads to more problems down the road.
Great documentation is the basis for great software
Documentation serves as a roadmap for the development process, providing clear and concise information about how a project is intended to work and how it was implemented. This information is essential for maintaining and updating the software over time, as well as for onboarding new team members. Good documentation helps to ensure that everyone is on the same page, reducing the risk of misunderstandings and errors.
In addition, documentation helps to improve the overall quality of software. By providing clear and detailed information about the design and implementation of software, developers can more easily identify and resolve issues, resulting in a better and more reliable product.
Types of documentation
When referring to documentation, most of the time people will think about the most commonly used types – code documentation or API documentation. But in fact, there are multiple types of documentation in the world of software development, and other variants can also be crucial for project scalability and maintainability.
Let’s look at a few of the most common types of documentation.
Process Documentation
Process documentation refers to documentation that outlines the various steps and procedures involved in completing a specific task or process. This can include anything from onboarding new people to the project to creating a marketing campaign. Process documentation helps to ensure consistency and efficiency in completing tasks, and can be used as a reference for training new people.
Code Documentation
It’s the type of documentation that provides information about the code itself, including variables, functions, and classes. This type of documentation typically includes comments within the code itself, as well as separate documentation files like API documentation.
Code documentation helps to ensure that the code is maintainable, readable, and understandable, making it easier to modify or debug as needed.
Well-written end-to-end, integration, and unit tests can also be considered code documentation, as they are executable and verifiable documentation that can be read as if you were reading system requirements.
The bare minimum for code documentation is a readme file that contains information about how to run the project, and how to contribute to it. Contribution guidelines might include things like information on coding standards and branching/release processes.
Project Architecture Documentation
This type of documentation is a combination of process and code documentation. Having a general overview of how the whole project works is very important. Architectural changes may occur in the project’s lifecycle, and it is important that they are documented, as the context behind some decisions may also change over time.
User Documentation
User documentation refers to documentation that is intended for end-users of a product or service. This can include user manuals, online help files, or tutorials. User documentation guides users to use the product or service effectively, reducing the risk of errors or confusion and improving overall user satisfaction.
Writing documentation saves resources
There are multiple real-life scenarios where clear and detailed documentation saves time, and with that money. One of the most common examples is onboarding new developers to the project. With clear and detailed project documentation, new developers need less time for project onboarding, as the documentation includes not only the project setup, but also explains the processes involved.
For example, documentation for onboarding a new developer will include notes from meetings with project managers, definitions relevant for certain tasks, notes from meetings with other developers to provide technical support for project installation, release process documentation, and so on.
Documenting a release process can be crucial for a successful release of the project. Even a simple checklist of things to do can be considered good documentation as it ensures that all steps will be completed.
For example, leaving out one step could lead to an unsuccessful release, which can cause delays and missed deadlines on the project. In this event, finding out which step was missed without documentation could be a huge headache.
Further, every project can be affected by changes in personnel, either from the side of the implementation team, or from the sides of the project owner or client. New project owners might not know the full history of the project, and the reasoning behind previous decisions. Proper documentation helps to explain why some decisions were made, and the reasons behind them.
Another example where documentation is crucial is when the developer is implementing a quick-fix or a hack in the code. Sometimes hacks are a necessary evil, solving a burning issue until a better solution is implemented. These situations must be documented so that everyone involved is aware of potential risks when removing the hack.
How to write good documentation
Write for the audience
When writing documentation, you first need to consider your audience. If it’s aimed at other developers, it can be more technical and detailed. However, when you’re writing for a non-technical audience such as stakeholders or end-users, documentation should be written in plain language, avoiding technical jargon.
Sometimes the audience types will overlap, and you should consider providing different levels of documentation – detailed technical documentation for developers and simpler, user-friendly documentation for other stakeholders.
Provide value and meaning
One of the most common pitfalls when writing documentation is not providing the backstory behind an initiative. You need to explain the problem that needs solving, how it should be solved, and why you need to do it in the first place. By providing answers to these three questions, the audience will easily get onboard with the problem and its solution.
Be clear and concise
Good documentation should be easy to understand. Use simple language and clear explanations of concepts and processes. Avoid using acronyms or abbreviations without explaining what they mean.
Additionally, be concise and stick to the main points, avoiding unnecessary details or tangents that can confuse the reader. Use the DRY principle of software development – Do Not Repeat Yourself. Provide simple and clear examples stripped of unnecessary details.
Use a consistent format
When it comes to documentation, consistency is key. Use the same format for each section, such as headings, subheadings, bullet points, and numbering. Add a table of contents and linkable sections if possible. This makes it easier for readers to navigate the document and find the information they need quickly. Additionally, consider using templates or standardized formats to ensure consistency across different documents and projects.
Keep it up to date
Documentation is only useful if it is accurate and up to date. Make sure to regularly review and update your documentation as changes are made to the project or code. This includes keeping track of new features or functionalities, changes to code structure or architecture, and updates to external dependencies or libraries. By keeping your documentation current, you can ensure that it remains a valuable resource for yourself and others involved in the project.
Use version control
Just like code, documentation should be managed and version-controlled. Using a version control system can help track changes to the documentation over time. Additionally, it can facilitate collaboration among team members, allowing multiple people to work on the documentation simultaneously, merging changes as needed.
Utilizing GitHub Copilot for writing code documentation
Code documentation is an essential component of software development, and AI can help you with it. By providing clear and detailed information about functions, variables, and other components of the code, developers can more easily understand how the software works and make changes as needed. This information is especially important for large and complex codebases, where it can be difficult to keep track of how everything fits together.
Using GitHub Copilot to write documentation can save time and provide great results. Here is an example of documentation written by GitHub Copilot Labs Visual Studio Code extension for the refreshToken function.
/**
* This function is used to refresh the current access token when it expires.
* If the current response is an OAuth2 protected resource URL (i.e. a URL that requires an access token to be accessed) and
* the response status is 401 (unauthorized), then a new access token is retrieved using the refresh token.
* If the current response is not an OAuth2 protected resource URL or the response status is not 401, then the response is
* returned without any changes.
* @param request The current request
* @param response The current response
* @returns A promise that resolves to the response
*/
async function refreshToken(request: Request, response: Response): Promise<Response> {
...
}
The function comment generated by GitHub Copilot Labs extension describes the context of the function and related parameters. The purpose and the application of the function is described in a detailed way, which provides value to the developer.
The purpose of code documentation should be to answer the question why, not how something works. Well-written and clean code should answer the how question by itself.
Despite the fact that the GitHub Copilot only deals with the “why” part, it’s a great stepping stone for kicking off documentation. For example, the provided example could be expanded with additional context on the cases when the token can expire and when this function should be called.
Common anti-patterns
Writing good documentation can sometimes be a hard job, but it’s a lot easier if you know what to avoid. Here are some common anti-patterns you might come across.
No documentation
This one is obvious: lack of documentation can make it difficult for everyone involved to understand how a system or a process works, which can lead to confusion, errors, and delays. It is important to have at least some level of documentation in place, even if it’s just basic notes or comments in the code.
Over-documentation
On the other end of the spectrum, over-documentation can be just as problematic. If there is too much documentation, it can be difficult to navigate and find the information you need, which can be just as confusing and time-consuming as having no documentation at all. It is important to strike a balance between providing too little information and overwhelming the reader.
Poor organization
Poorly organized or poorly structured documentation can be difficult to navigate and understand. It is important to use a consistent format and structure throughout the document, with clear headings, subheadings, and bullet points. Consider using tables of contents, glossaries, or indexes to help readers find the information they need quickly.
Outdated documentation
Outdated documentation can be misleading or inaccurate, leading to errors and confusion. It is important to keep documentation up to date as changes are made to the system or process.
Writing for the wrong audience
Documentation that is written for the wrong audience can be confusing or irrelevant. Make sure to consider who the intended audience is when writing documentation, and tailor the language and level of detail accordingly. For example, documentation intended for developers may be more technical and detailed, while documentation intended for end-users may need to be more simple and user-friendly. It’s kind of like an iOS developer wanting to learn about the DocC documentation environment and reaching this page instead. They would be much better off reading the article Documentation Is the Key to Happy Coding, for example.
Documentation ensures you deliver quality products
In conclusion, documentation is an essential aspect of software development. From feature documentation to process documentation and code documentation, it provides the foundation for clear communication and understanding. Good documentation also reduces the risk of misunderstandings and errors, and improves the quality and maintainability of software.
With solid documentation in place, clients can save time and money in the long run. When everything is properly documented, onboarding new developers to the project is quicker, it’s easier to manage changes in staff and monitor the release process.
To make your documentation effective, it’s important to consider the different types available, such as process documentation, code documentation and user documentation. Additionally, it is important to avoid common anti-patterns, such as lack of documentation, over-documentation, poor organization, outdated documentation, and writing for the wrong audience.
By prioritizing documentation and following best practices, developers and other stakeholders can ensure that they save time and money, avoid common problems, and create high-quality products for their clients and users.
