Oversights

A common issue we kept running into at Polyconseil is the curious case of outdated documentation. Naturally, we write a ton of documentation around our software: technical choices, design breakdowns, setting up a project, testing, etc.

However we realised that most of the time a documentation is not useful right away, it might take time for people to actually feel the need to read it. They might have contributed writing it, know the underlying project well enough, or have nothing to do with this at all.

This leads us to situations where people read the documentation months later, with little or no prior knowledge, sometimes being brand new recruits. We take time to update the documentation when bringing major changes to the code, but minor or subtle changes often go unnoticed (e.g. updated dependency). The discrepancies between the documentation and the actual implementation grows bigger and bigger, leading to potentially incomplete but also misleading information.

In order to solve this issue, we wanted a way to remind us when a documentation was getting a bit old and might need proofreading.

Time to dust it off!

That's how we came up with sphinx-dust, a small, simple Sphinx extension that emits warnings when a document hasn't been proofread for a given number of days. sphinx-dust introduces a new directive to insert in a document you want to monitor:

.. reviewer-meta:
    :written-on: 2016-09-01
    :proofread-on: 2016-09-20

This has two effects:

1. it will emit warnings that you can transform into errors using Sphinx's -W argument (making your CI build fail for example); and,
2. it will generate a note just like this one (YMMV according to your CSS rules):

This gives you both some context in a human readable form, and, with a proper CI configuration, notifications on possibly outdated documentation. If you just want the note generation, you can disable warnings by setting the dust_emit_warnings variable to False in your conf.py file. This way you can benefit from a consistent, human-readable metadata about your documentation.

In the following months, we plan to setup this plugin across our various projects, tweaking the dust_days_limit for each one in order to find the sweet spot between documentation staying outdated for too long, and us getting sick of reading documentation every day!

Stay tuned for some feedback, and don't hesitate to give sphinx-dust a try, contributions are welcome!