Skip to content

Keeping documentation up to date

Problem

As we strive to reshape our approach to documentation, we are going to inevitably need to deal with the problem of aging and outdated documentation. In fact, parts of existing documentation are likely already outdated and need further review.

Solution

One approach to help with this problem is the following:

  1. Documentation pages will be written in Markdown and their Frontmatter can have metadata on when the page was last reviewed and by whom.
  2. We can build a small piece of automation to parse this and let it create issues for pages that need further review.
  3. These issues can be assigned out to a team member, who then reviews the page, bumps the metadata information and pushes this back in.

This enables us to also measure how current our documentation base is: We can derive an overall percentage of pages that are beyond their desired review timelines and e.g. state that 95% of documentation is up to date. This will help us track how well we're doing in this area.