Around 90% of the teams I have worked with in the past 22 years have never, ever, documented anything. Not a single wiki page, not a README file on top of a repository, not a single PDF file for the end users, not even a single UML diagram. Where they successful? Hardly.
Such dysfunctional and dystopian organizations, regularly release software without any kind of written documentation for human beings. The excuses for this situation range from the pitiful (“documentation is always out of sync with the code”) to the infurating (“engineers are not good at writing anyway”) to the downright outrageous (“the code is self-documenting.”) As my friend Graham explained recently, code is not the final product of a software engineering team; the final product is the solution to a particular problem, which incidentally, happens to be provided as code.
In a world of Turing-complete languages, the choice of the programming tool used to generate that solution boils down to irrational personal preferences and economic constraints, only. In such a point of view, which the author of these lines has irrevocably and adamantly sustained for decades, documentation is a conditio sine qua non for the final solution of said problem.
Let us be very clear in this point. There is, and there cannot be, any software without human-readable, documentation.
Having said that, it is commonplace to observe that for some inner reason, most software developers have an innate, deep, absolute hatred of using keyboards for anything else than cranking out code. Can one blame them? Not really. The truth is, the whole education system is built in such a way that it is a de facto writing hater factory.
Kids are told to write dissertations and later papers, a dry and lonely activity. Those papers are graded with red pens, filled with scribbles, with illegible or otherwise undecipherable comments, and more dissertations and papers follow, one after the other.
And then one day, before they graduate, they are told to write a thesis, around 14’000 words. The mere thought of counting words, even if automated, adds weight to an already dreadful exercise. There is even the legitimate concern that some automated software will flag those texts, as a false positive case of collusion or plagiarism.
Writing is an act of nervousness and tension, certainly not pleasure.
And then there is the problem of tooling. Most people relate the word “writing” with Microsoft Word, which is a sad association. They do not only dread the act of writing, but they came to abhor the tool they must use to pour their thoughts into. And even worse, they might as well have witnessed the thing crashing down, taking to oblivion the effort of the past few hours of work. Some others have similar experiences with tools like Atlassian Confluence or other wiki engines, and with some ill-conceived tablet applications.
The problem is when the whole act of writing, unfortunately associated with deficient tooling, is sent to the garbage bin in a single sweeping gesture.
No wonder apps like WriteRoom, iA Writer, and Ulysses, became so popular among writers in the past decade. No wonder why the latest Freewrite sold out. If you decide to write seriously, you actually need a tool that will work with you, not against you.
I am not here to advocate for the use of Asciidoctor, Markdown, or even LaTeX (although I will if you ask me.) But I would rather have teams write text in Notepad than in any other tool. I would rather have software teams write something at all, at least a couple of paragraphs a day, describing their current work, their current designs, their current statuses.
Besides, the idea of all of these tools is actually the same: to remove the friction between the brain and the fingers. All modern computers already understand plain text per se (arguably, UTF-8 is one of the greatest inventions of all times,) and come usually bundled with a keyboard; you do not need anything else to transform your thoughts into a digital form. And the consensus among writers is, indeed, that dropping Microsoft Word is the first step towards writing happiness.
The healthiest teams, the most productive teams I have ever worked with, wrote everything down. In excruciating detail. They even had some ISO certification which actually forced them to have everything written down. They even had “peer writing,” “extreme writing,” and “mob writing” sessions, all together collaborating on some document simultaneously. Writing documentation was considered an integral part of their delivery process, not an afterthought, not a nice-to-have, not the job of somebody else.
But, of course, there is a first step to actually start pouring those words on paper. Almost 20 years ago, Joel Spolsky famously said that “writing is a muscle.” So close this browser window, and start writing about your software.
Cover photo by Danielle MacInnes on Unsplash.
