How I (try to) make documentation not boring

Documentation, in its traditional way of how it has been written since the dawn of Software development, is mostly boring.

It’s boring for who is writing it and those reading it – it’s even boring for the ones who have to manage it because you should keep it there “for rainy days”

I think the reason for that is the definition of what documentation is.

Most of the times, people think of long github pages, a maze of confluence pages or, in its fanciest form, colorful Notion pages with embeds, tables and funny images. This is when documentation becomes an ordeal – a thing to do when “you have time” or when “someone asks you to” or if you are “offboarding”.

I think documentation is a living matter – any sort of written trace of:

• Why
• How
• When
• By Whom

something is being done, and if this happens in a natural channel of communication for one or more members of the team – so be it!

In other words, for me – a Jira ticket, a Slack chat and a Whatsapp message is all documentation!

Important caveats to note with this approach:

• If documentation is a federation of natural channels of communication, organization of information so it becomes transparent to all project stakeholders becomes key
  • simplified: if important information is communicated in a Teams chat by a developer and a BA, putting a screenshot of that discussion in a Jira ticket is totally ok
• Meetings without agenda or written conclusions are the nemesis of documentation
  • Here I try to follow a simple rule: meetings are for conclusions, not for familiarising others with the topic

So how does this take the boredom out of the equation?

With this approach, a centralised repository tool of documentation (e.g. your confluence pages) become more of an index where you can find conclusions that have been communicated by team members, rather than something written in the first and last 5% of the project because “it’s good to have documentation”.

With this approach, teams have an incentive to communicate effectively in written form, because they are “auto-generating” traceable documentation for decisions pertaining to the project.