Dec 15, 2022
On writing documentation, while making software
Maximizing efficiency and minimizing errors through documentation-driven development
Creating documentation is one of the essential parts of software development. To be honest, documenting things is hard. The main purpose is always going to be ‘getting things done’. While completing given tasks, there has to be a time frame for creating some documentation. So, why are we wasting time writing documents rather than implementing the feature?
There is an efficient and useful approach called Documentation-driven development. It dictates you prepare documentation before or alongside the actual code. You simply create documentation that contains every aspect, detail, and usage of your implementation. It helps to ensure that all stakeholders have a clear understanding of what the code is intended to do, how it should work, and how it fits into the overall project.
If it’s not documented, it doesn’t exist.
The team or the person who develops the product cannot be sure how the software works without having documentation while adding a feature to it or inspecting it. Well-written documentation can serve as a reference for developers as they are writing and testing the code. This can save time and effort, as developers do not have to constantly switch between the code and other materials to understand what they are working on.
Single source of truth
Having a single source of truth is important because it helps to ensure consistency and accuracy across all aspects of the project. By using a single, authoritative source of information, developers and other stakeholders can avoid misunderstandings and conflicts, and work together more effectively towards a common goal.
It could be the project’s design document, specifications, or other forms of documentation. It is important to keep this source up-to-date and accurate and to use it as the basis for all decisions and actions related to the project.
README File
A good way to start off with your code is by creating a README file. The README is an essential piece of documentation for your code, as it provides an overview of what your code is all about and its main purpose. This is important, as it can be difficult to convey the purpose of your code through code comments alone. By having a clear and concise README, you can give others a quick and easy way to understand the purpose and functionality of your code.
It shows the big picture of the software’s architecture and functionality. This document should include information about the main parts of the system, how they will work together, any important facts that will affect how the code is designed, what are the main packages or patterns of the project.
Easy onboarding for newcomers
If you join a company that has well-documented resources, it feels like being in heaven. Documentation-driven development can have a positive effect on the onboarding process for newcomers by providing clear, concise information about the project and how to contribute. This can help reduce the time it takes for newcomers to become productive members of the team and serve as a reference as they continue to work on the project.
So, the preferred order of operations for new features is:
- Write documentation
- Get feedback on documentation
- Test-driven development (where tests align with documentation)
- Push features to staging
- Functional testing on staging, as necessary
- Deliver feature
- Publish documentation
- Increment versions
Documentation-driven development can help improve communication, collaboration, and understanding within a development team, which can ultimately lead to better code and a more successful project.
Thanks for reading!
References:
