Over-documenting

17 Jun 2024

In terms of working on a codebase daily, if there’s one thing that I wish I’d done sooner, and also wished that the engineers before and that still works with me, is to over-document everything.

By the statement above, I hope you can already understand what I am talking about. With complete documentation, you can easily find out what a function does, what it returns, what parameters it takes, and what it throws. It’s like a book that you can read and understand.

Some might even call it a “documentation-driven development”.

The challenges

But, I can see a few challenges that we might face in order to make it into a reality:

1. Structure

It’s become a shamble if lengthy documentation doesn’t have any meaningful and understandable structure. If it’s a novel, it’s like you jump to a different act on each page. It doesn’t make sense at all.

For this, I personally really favouring the Diátaxis framework. It’s built by developers and really puts developer needs in mind. But, it is still versatile enough to be suited to each team.

2. Maintainability

Once you have put a lot of “content” in your docs, maintaining it and keeping up to date with the real system is a challenge. And no, if you think that making autogenerated documentation from the codebase is the solution, it’s far from being sufficient (read here to dig more).

For this one, I can only think that habit and discipline are the only key. I might be wrong on this one, but that’s all I got for now.