The Documentation Conundrum

Any typical code base, given enough years, becomes large enough to find it difficult to maintain documentation for. Every new piece of code I saw in my career had one of the below 3 issues with regards to documentation :

1. No Documentation
2. Incomplete Documentation or
3. Outdated Documentation

So I started on a quest to find out what’s the best way to document your application and the internal implementation, and I shall try to summarise my findings to the best of my knowledge.

Tests are the best form of Documentation

One wise programmer once told that you won’t need any documentation if your tests are perfect. Well, he was right. But for that to happen you need to follow TDD (Test Driven Development) - where you first write a test, then fail it, then write code to pass that test - and iterate until your implementation is ready.

Whoever does TDD well, has the perfect little suite of tests sitting right inside their code base, telling a clear story which no other document can explain.

Coding Conventions make life easier for everyone

I don’t need to stress much on this subject, as it’s a familiar topic to you all. Naming Conventions, Comments, Class/Method descriptions and many more rules that we set for ourselves, if followed, also ensure we can have great documentation.

In fact you can use libraries/frameworks like java-docs, Sphinx etc to generate docs directly from code.

Wiki pages are outdated unless you enforce

Domain documentation is a tough problem to solve, and there is a good chance that whatever path we take, it eventually grows outdated as it can’t keep up with the changes being pushed in by the team. Wiki pages make sense at a HLD/LLD level, and to keep them updated as design gets updated during development, but beyond that, using it as a repository of all documentation possible - is not a smart solution in my opinion.

Please use README .md and API Docs well

The best documentation is not something that sits outside your repo (like a wiki/confluence) but something that can be found right when the developers open up the repository or clone it.

What better place than to use the markdown documentation to ensure at least application level docs are updated there on a regular basis.

Versioning (Change Log) matters

This is something I saw being followed very well in open-source repositories and it’s clearly a useful history of the changes that went in. It wouldn’t classify as official docs any day, but it’s a really useful addendum to the documentation if you ever want to figure out recent changes that went into application code.

Docs as websites

Docusaurus, Gatsby and other static side generators work really well. I am still experimenting with them, but my take is that they are good for external facing documentation, Public APIs etc. but for internal documentation, it might get really tough to ask the team to keep the docs updated along with the rapid pace of changes flowing in every day.

There is clearly no silver bullet to fix the documentation conundrum, but a situational approach to decide where to host the documentation for an application, tech stack, domain, or a simple change - can make life much easier for future generations of developers who will probably applaud you for doing a good job at maintaining docs. If you have any better suggestions, please leave a comment or respond to me via email.