Intro
In part 1, we established why documentation matters and explored the mindset shifts necessary to prioritize it within development teams, as well as some practical first steps. Now we’ll focus on integrating this mindset into everyday development workflows. The following explores some strategies to integrate documentation into the development process, as well as some common pitfalls and their solutions. Whether you’re just beginning to build a documentation-oriented culture or strengthen existing practices, this will help you create sustainable, value-driven documentation usable company-wide.
Making documentation part of the development process
In order to make good documentation a fully integrated part of the development process, it is critical that the organization adopts the mindset that “Code is not complete without documentation.” This means two things. First, for new projects, it means the project is not complete and signed off on until all documentation standards are met. It also means that when updating existing projects, any documentation that pertains to the updates that were made needs to be updated as well. As mentioned in part 1, the time to create or update documentation needs to be included in sprint planning to ensure that developers are given adequate time to document code and systems properly.
There are some great ways to make sure that this is done, including integration into pull/merge request checks performed by senior developers and having automated systems in place to check for documentation updates. The first of these is definitely the easiest. If word comes from the top down that code reviewers are to check for documentation as part of their reviews, in theory, no code should be checked in that is not properly documented. Another great aspect of including this in code reviews is that developers begin to think in a more system- or organization-based way. Documentation reviews should be included in code reviews and considered just as important, and developing standards for reviewers to use during reviews is critical for consistency across different teams and projects.
Adding checks to repository creation, checking for things like READMEs or linters that check for things like proper swagger documentation or function headers, are some great automated ways to check for proper documentation as well. One great thing about automated methods is that nobody has to remember to do it; it is just part of the process. However, if a given team chooses to do this, the main point is that documentation needs to be thought of as just as much a part of the development process as writing code.
Another great way to make documentation a core part of the development process is to begin with it. Starting with clear requirements documentation starts projects’ life cycle out on the right foot with some good docs rather than playing catch-up after the fact. Well-documented requirements often will double as system documentation after the fact, though it is helpful to version them so that as time passes, it is easy to understand how the most up-to-date version of the system works.
Lowering the barrier to entry
To ensure developers use the time they have been given to document a system well, beginning with tools that have a low barrier to entry is usually how teams should start. One of the best ways to do this is to start with READMEs, a common document that accompanies almost every codebase with some basic overview information, as well as instructions on how to use it. If developers are starting with good READMEs, they don’t have to go outside the project they’re working on to work on documentation. Whether in a README or in a wiki, templates almost always improve documentation. Clear templates give both creators and readers of docs a good idea of what kind of information they can expect to find and create consistency across different projects in an organization. Documents should be easy to find for everyone in an organization as well, keeping the audience in mind. READMEs are generally geared at other developers, whereas something like a wiki is likely geared towards project-level management and above.
While having templates and standards is very helpful, there is absolutely such a thing as too many standards. In software development, the term Minimum Viable Product (MVP) is often tossed around to describe the absolute essentials for a project. Similar to this, documentation standards (and standards in general) should adhere to a Minimum Viable Standards (MVS) rule. The goal of standards is to enforce consistency across an organization. A good rule of thumb is to look at standards and ask questions such as: “Is this adding measurable business value?” and “Is this document a reasonable length given my audience?”. While it is very important to have standards, if you are documenting for the sake of the standards rather than driving value for the business, you have likely gone too far.
Common Pitfalls and Solutions
Some common pitfalls when trying to implement a company-wide documentation initiative are as follows:
- Perfect is the enemy of done: Working iteratively and consistently is key, and it is important to remember that, in general, incomplete or inadequate documentation can be better than no documentation. It is also important to know when good enough is good enough, based on the audience. You don’t want developers to move from spending no time on documentation to spending all their time on documentation. Having reasonable goals as part of the sprint cycle and getting all that is possible done is a great way to avoid this. If docs are consistently coming up short, start by figuring out what about them is coming up short and target that.
- Docs become outdated fast: This is very common with systems that are backend-oriented, such as APIs, especially those that don’t use something like Swagger to keep up with changes. Changes to docs should always be made along with code changes to avoid this, and regular audits of docs can also be a huge help here.
- Nobody can find anything: This is something that is often seen in organizations where developers write mainly code-oriented documentation. The average business manager is not likely to know their way around GitHub, GitLab, Stash, etc. The key here is making sure docs are organized both according to function and according to audience. Regular tours and showcases of docs to management at sprint reviews can also be very helpful here.
Conclusion
Building a documentation culture is not a one-time initiative – it’s an ongoing commitment that requires strategic planning and practical implementation. By integrating documentation checkpoints into the development process, we ensure that docs are created for all software projects and also kept up to date. Treating documentation as equal to writing code, not an afterthought, helps people across the organization understand the value of docs as it accelerates onboarding, reduces time spent on frequently asked questions, reduces technical debt, and empowers executives to make informed decisions. The teams that succeed here are not those with the most comprehensive one-off documents, but those that consistently commit themselves to creating them for systems and keeping them up to date. With the strategies outlined here, you have a roadmap to embrace the documentation-oriented culture; one sprint, one project, and one well-documented feature at a time.
