The hardest thing about documentation is keeping it up to date. One thing that helps is having a formal system to make sure you regularly review the content.

At GOV.UK we have given all our docs pages a “review-by date”. After this date the content must be reviewed.

Configuring the review date

Each page has 3 variables: the date it was last reviewed, who needs to review it, and how soon the page should be reviewed again. It’s configured in the middleman front matter of the page.

Pages that are likely to change soon will typically have review dates of a month or so. Others are more static and are set to 6 months or even longer.

Showing review dates

Every page has the owner and calculated review date in the footer of the page:

Pages that need to be now are displayed on the docs homepage. We also show the pages that will need review in the next week.

Once a page is expired it will show a prominent warning. This means the reader will see that it may no longer be current.

Slack

Each page also has owner. This can either be a Slack channel or a Slack username. Once the page expires, the owner will be notified in a message. This is done by our documentation robot, which is currently named “Daniel the Manual Spaniel” for unclear reasons. It runs every weekday at 11:30.

The notification will keep repeating until the page is fixed.

Further reading

Here are some useful links: