All documentation is incorrect, so write it as a news article

All documentation is incorrect in some way. But just when you write it, it is likely the most correct it will ever be.

Documenting a digital system (or any system for that matter) outside of the system itself is really tricky.

When the documentation is separated from what it describes, the two will inevitably drift apart over time.

You make a change and forget to update the documentation. Or you may not even realize it should have been updated.

Suddenly the documentation is lying, telling things that are not true anymore. Sometimes it will even say things that have never been true at all.

Keeping the documentation updated is a really tricky problem.

🗜️ One approach is to integrate the documentation with the system. The closer the integration, the more likely that both stay synchronized and change together.

🗞️ A complementary approach is to embrace the inevitability of change. To think of the documentation as a series of news articles or blog posts written over time. Each is never perfectly true, but most correct when it is really fresh.

In software development there is a practice called a pull or merge request. A set of changes to the source code that you want to make, together with a description of the changes.

Sometimes this is used as a way to enforce quality inspection, with a staged handoff between persons and roles. This is usually bad. There are much better ways to improve quality, such as working continuously together at all times.

But what I find valuable is how this gives an opportunity to summarize the current knowledge, give background, and outline the potential implications of a change.

As a description of the proposed changes you could:

🏛️ Give background and describe what you (think) you know right now.

🏗️ Describe what changes are being made and why they were chosen among all possibilities.

📈 Walk through the potential consequences, good or bad, that follows from the change.

Whenever someone wonder about your reasoning they can then go back to this description.

Frozen in time, it might not stay correct for very long. But it may help the people from the future to understand your reasoning at the time.

And hopefully they will thank you for taking the time to document the state of your knowledge.