It feels like the myriad schools of thought concerning the ‘right’ way to document software designs and comment code have been around since the dawn of time. These topics invite furious debate wherever they go and yet the conversation never really moves on, seemingly doomed to be stuck in a subjective tug of war that there’s no point in really winning.
To be crystal clear, documentation is important. Anyone who thinks otherwise is a fool. With that said and without, I believe, the need for further justification, the goal of this article is simply to explain what it means to document effectively.
Fundamentally, all software development is authorship. There is a need to design something that requires software. You produce a design (hopefully) and you translate it into source code, and you beaver away, iterating until you have something that meets the brief (hopefully). Then you’re done — you’ve created a piece of written work using some language that, when realised, provides the solution to some problem or in some way enriches people’s lives (hopefully).
But of course, you’re rarely done. You return, you re-read, you tweak, you share, you publish. Software development is authorship — there is an audience.
So then, when it comes down to it, documentation is simply a tool to help you, as a software professional, communicate better with your audience, whether that’s a client, a community, or your future self. To document effectively is to have the confidence and the humility to consider the needs of your audience and write for them.
It’s worth dwelling on that for a moment; it’s the primary takeaway from this article.
To use the commenting of source code as an example, those who don’t add comments to any of their work and preach the notion that “good code documents itself” are poor authors. Of course, it is often true that implementations are indeed straightforward enough to be read by the desired audience and understood without further information. But what about that huge state machine? What about that 100-line block of crazy syntax? Does that document itself, really? To shy away from documenting software like this doesn’t show wizardry, it instead tends to betray a lack of confidence in the implementation and a lack of humility for not bothering to explain it.
On the other end of the scale, those who comment everything are similarly poor authors. Think of picking up a novel and seeing that every line is annotated with an obvious commentary, simultaneously patronising you, making it hard to understand the narrative and demonstrating that the writer wasn’t really sure in their own work. You’d soon put the book down.
Documenting effectively is learning to have enough confidence in the software you produce to have the confidence to be able to explain it. It’s having the knowledge that tells you that the majority of your audience will understand ‘that’ part of the design but ‘this’ edge-case could do with some qualification. It’s having the humility to appreciate that a 1-line bit of magic would benefit from 2 lines of context. It’s being a good author.
