Keep Your Documentation Up to Date with a Checklist

In a previous post, we discussed five types of code documentation and how to use them effectively in a software project. While knowing the different types of documentation is a helpful start, every software project faces the challenge of keeping documentation up-to-date.

Documentation can become out-of-date due to various reasons, including a lack of maintenance, changing requirements, and limited resources. The longer documentation goes without updates, the more challenging it becomes to bring it up to date. Here, we’ll discuss a checklist of items to review when making changes to a codebase to keep documentation accurate and reliable.

Inspiration

Atul Gawande’s book, The Checklist Manifesto, illustrates how checklists can enhance the quality and efficiency of various tasks. Inspired by his work, I’ve recently utilized a Documentation Checklist to help keep my software documentation up-to-date while saving time and effort. The author incorporates key elements to review when making changes to a codebase. This checklist is designed to keep documentation accurate throughout the software development process.

I recommend using this checklist each time you check in code to your codebase. One way to make it easier to remember is to incorporate it into a pull request template, serving as a helpful reminder to “check in” before “checking in.” The checklist consists of brief, yes-or-no questions you can mark as complete. It’s simple to use and integrate into your workflow.

The Documentation Checklist

Do we need to update documentation for any of the following?

1. Newly added/changed functions or variables
   Using standardized documentation formats, like docstrings or JSDoc comments, can help developers understand the usage of functions without needing to read their implementation.
2. New dependencies 
   It’s useful to document external libraries within a README or some other file so other developers know what they’re being used for.
3. Local setup changes
   You should keep the steps you need to get the app up and running locally s up-to-date to make the onboarding experience smooth for new developers.
4. New environment variables for the app to run correctly
   Environment variables, such as API credentials, aren’t often checked into the code itself. Maintaining an .env.example file helps other developers know which environment variables they should set on their machines.
5. Changes to the testing or deployment processes
   These are often automated. However, it’s helpful to maintain good documentation on testing and deploying your code, in case developers need to do them manually.
6. New business rules, logic, or assumptions
   This helps developers understand the intent behind the code and how they should use it. You can document this information within the code itself, in separate documentation files, or in a knowledge base or wiki.

Investing Time Upfront

This checklist’s items are a good starting point for maintaining the documentation on your projects. Depending on your project needs, you may want to add or remove items from the list. Consistently updating your documentation as you push new code can help reduce the need for a major documentation overhaul at the end of a project. It can also make it easier to hand off projects to other teams. Overall, investing time in updating documentation saves time and effort in the long run and contributes to the project’s success.