Currently, agile methodologies are used as a bad argument for scarce and low quality documentation in software development projects. The agile manifesto does not advocate for the extinction of documentation; it asserts that it is better to have working software than lots of documentation. While it's understandable that code is the priority, we also need to understand that good documentation correlates to better, safer code.
In this article, you will learn why code should be documented and why developers sometimes avoid writing documentation. You will also see tips for good documentation, understand how documentation improves software quality, and discover tools to help you raise the quality of your docs.
Why code should be documented
Time spent on documentation translates to hours saved by not duplicating R&D and searching Slack channels. A well-documented system depends less on individual people, and more on the cooperative realization that documentation is valuable and should be treated like code.
The code you are developing today will be used by you and others in the next few days, in the next few weeks, in the next few months, and maybe, in the next few years. Enterprise organizations are still running and maintaining critical business logic code that was written decades ago.
The documentation will also help in the insertion of new team members, and developers report higher job satisfaction when they have accessible documentation that they feel like they can consistently trust.
Finally, when you take the time to document your software, you will have time to think carefully about what you are developing; this can bring insights and ways to better implement a certain functionality of the system. You're prescribing the end results that you need to create. Think of documentation like a blueprint, and when coupled with good tests, a fast way to develop software iteratively.
Why developers do not document their code
There are some reasons used in software development teams for not documenting code, let's learn the most used and known.
Writing is hard
Writing is not simple and software documentation is only valid if it is well done and produced in a critical, clear, and concise way. This takes time and dedication, and brings additional scrutiny on those that create it. We need to accept this, and support and encourage our colleagues to write.
Lack of documentation does not block delivery
Lack of documentation does not prevent the delivery of a software, so if it does not block, developers tend to put it off. Well-documented code, however, speeds up the inner developer loop which allows you to push more features with greater safety and client satisfaction.
There is no time
The biggest fallacy of all is "There is no time", which actually has a tiny bit of truth to it. If your PM / Growth Managers don't account for some time to write documentation in a sprint, it's often skipped. Then, you spend an entire sprint fixing all of the documentation, just to see it go out of date again. This cycle only breaks if there's cooperative prioritization of the documentation, as the value of having it is explained.
Customer will not use and are not paying for it
It is wrong to say that the customer will not benefit from internal-facing documentation. There are many ways that customers directly benefit when developers have access to great documentation:
- Features can be shipped faster, and safer, with fewer regressions and bugs.
- Customer-facing documentation is more accurate because the technical writers that produce it can draw from known-good reference within the internal-facing documents.
- Sales engineers can answer questions faster, which leads to more leads being closed sooner.
Tips to good documentation
In order to help to build effective and well documentation, you can follow these 5 steps:
Write before coding
One of the most important tips and one that is most overlooked: write before coding. Often developers just sit down and start coding, not stopping to document what is going to be implemented. Writing before coding has several benefits such as:
- Take time to think about the best way to implement that feature;
- Have a whole software vision instead of just focusing on new feature, avoiding side effects and negative impacts on other features;
- Documenting more clearly and making it easier to understand, if the documentation is done later, the tendency is for it to have much more of a verbalization of what was codified, than a detail of it in a clear way for anyone to understand.
- What did you think before development?
- How will you implement it?
- Why will you implement it in this way?
- How will different kinds of people use it?
Track documentation changes
As with code, documentation needs to be tracked when updates are made so that it is always associated with a particular version of the software. Almost nothing gives developers more anxiety than the documentation they just read not lining up at all with the code they're supposed to work with.
Versioning the documentation in the project repository is the best way to track changes and avoid surprises in the future. And like all things in source control, you always have the luxury of going back in time.
Document decisions and discarded alternatives
It is very important to document the decisions that were made, both the choices that were made and the alternatives that were discarded. In the future, you will often need to know why you made that decision!
Why software quality could be improved when documenting is done right
One of the biggest gains in product quality is when you start testing as soon as possible. As you start producing documentation before developing the software, you can review this documentation to find possible bugs, even before the code is implemented. You start building things more deliberately.
With documentation being the shared truth about what's being developed, everyone's understanding of what needs to happen will naturally come closer together.
As soon as the code is ready to ship, versioned documentation becomes a story of how it began, and why directions were chosen and implemented.
Finally, when the solution for a feature is well built from documentation, it will serve as a reference for future implementations of similar features. Great documentation helps you create reusable components because it talks about the use case, not just the implementation. If you implement tags in a very efficient way, you've got something you can get a lot of value from, and point to existing functionality as reference.
How the right tool could help
There are several tools that can help developers collaborate using documentation. They must make the process simple, not constrain the writer, keep the document in sync with the code it references, and make sure the documentation is visible and findable. They should also help you manage versions.
In this article, some features of Swimm are highlighted, which is a tool that creates documentations coupled with code and integrated into a workflow:
- Easily create walkthroughs, tutorials, and smart documents directly from your codebase;
- Tree View enables to quickly search which files and folders have corresponding Swimm tutorials;
- Auto-Sync algorithm automatically suggests changes to your documentation as the code evolves, verifying tutorials stay up to date;
- Create a tutorial from a pull request.
We learned about the problems that lead to documentation being ignored, the benefits of treating it like it's as valuable as code, the importance of cooperative maintainer responsibility among entire teams, and how Swimm can help with all of the documentation challenges.
Code documentation has an array benefits to a software, in addition to increasing the quality of the product. It is worth investing time to produce simple, concise, and effective documentation and enable code collaboration.