The art of good Documentation

As the progression from a junior developer to a senior one continues, there is a point where you realise the importance of good documentation. Too often there are situations where documentation is kept as an after thought and this leads to a situation similar to this:

  • There is a huge amount of documentation but it is extremely unorganised
  • There is no documentation at all
  • The documentation is poorly written and has no audience in mind
  • The documentation is in multiple places and is now out of date

If you’ve experienced or are still experiencing the above, this article is for you!


Why is it hard to get documentation right?

The reason documentation is kept as a after thought is the same reason why tests aren’t always written or why security isn’t always considered.

Documentation isn’t critical to a business. It isn’t necessary until you really really wish you had it.

Poor documentation is the result of priorities for the developer. Only with experience do you realise the importance of documentation. Just think about documentation as tests or security. They are a safety net to help you move faster in the future.

The best way to get documentation right, is to create a culture of writing while coding.

Code isn’t the only archifact a software engineer produces


How do I start? How does good documentation happen?

This is the real meat right here. How do we start to output good documentation? By changing culture.

Make it obvious what documentation *must* be written along with a feature. If there is no process in place for making sure documentation is kept organised and up to date, guess what? It won’t be kept organised and up to date.

Start simple with the process. An Example might be: before a JIRA ticket is complete the relevant documentation should be added. By breaking it down into bite size chunks, it makes it a smaller investment.

Here are some tips and tricks that will help you get on your way to decent documentation:

  • Be precise about what artefacts are required for a feature to be *completed* and that these artefacts include documentation.
  • Version your documentation. Keep it relevant or at least make it known when it is not relevant anymore through versioning.
  • Add documentation owners. Empower these people to make sure that the documentation is well written and organised.
  • Follow the same processes used for your code to write documentation. This makes it intuitive for newcomers.
  • If you can, try and make sure your tooling is easy to use but not too easy. You want writing documentation to be part of the process. If its written intermittently and inconsistently, it will never be organised or up to date.

Hopefully, this guide has provided a rough idea of what it takes to write good documentation. In the end, its all just culture.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade