Based on my observations, the thing that really stands in the way of “just writing documentation” are mediocre tools we are given. (I’m ignoring lack of time for technical-debt repayment, which is a great topic, but out the of scope of this article.)
Too rarely we select documentation tools ourselves. Too rarely we even consider that there is a choice, or that it might be worth our time to use something else. Seriously… In this industry we work with tools and technologies we spent years to master. Finally, they are becoming a fundamental part of our every-day’s workflow. Some of us have even strong opinions on them (in the end, we are not bots, but human being – emotions are humans natural characteristic, even if evolutionary importance of them isn’t always that obvious). I know a guy that has Debian1 spiral tattooed on his back; recently I read that some people wouldn’t even try editor without dark mode; I read once, years ago, that a team wasn’t allowed to use CocroachDB, because management didn’t like the name.
I’m pointing this out because I don’t see a reason why parts of our work shouldn’t be rationally evaluated. It shouldn’t be like that if the final choice may have a bad impact on documentation development process and there is just lack of willingness on our side (unfortunately it ends like with lack of willingness to write automatic tests, or perform code-review: we-from-the-present are just making daily work much less enjoyable for us-from-the-future… and technical-debt may have a very high interest). But it especially shouldn’t be like that if we are simply forced to use tools chosen by people that in the end are not even going to use them themselves.
Knowing all the above considerations, now is a scenario: someone important above you in hierarchy suddenly realizes, “there is not enough documentation in a project, and documentation must… must… must happen! Developers should write it in… yeah we’ve got already this most popular task management tool (let’s call it Gerry). And this tool is accompanied by articles writing tool (let’s call it Constantine). If everyone loves Gerry (at least I heard from upper management, that for our Scrum-projects-quarterly-reporting-maintenance-assisted-execution it offers a range of great charts with hours worked vs hours estimated measurement) …I bet developers will love writing documentation in Constantine. Yeah, I won’t even ask them!”.
So, Constantine really is dominating industry, therefore (one could think) it should offer at least some of these things: flexibility, respect for habits developed from browsing other websites with industry de facto standards, advanced configuration options, and (the most important) optimization for speed under heavy load.
Well, you should already know where I’m heading with this tone (or what is actually called Constantine real-life equivalent… Pssst, they both start with C).
I’ve actually been in a team where we just got a task to “document everything in this tool we got for you”. Fortunately I really didn’t know what I was doing at that time. Unfortunately someone inherited documentation I wrote back then.
In case of my personal experienced with tool C…, the worst failure I’ve experienced was, when I revisited some old documents and to make things a little faster, I opened the next 10 documents in browser tabs. I mean, nothing fancy… After waiting for about 5 minutes for them to fully load as websites (the spinning wheel disappear from browser’s tab), then to actual load content, and then to load all these nested widgets that alter website’s layout all the time… computer has run out of memory.
Even if it’s not tool C… but other advertised solution, where focus on power-users is sacrificed to better fit users of much different requirements (usually also much closer to decision-making and contracts signing, than actually using them in greater extent), the main contributors of documentation are simply abandoned. When a simple update in specification, instruction extension, or a sketch of new document, requires too many clicking and waiting for web-site to load (switch from code editor, open documentation tool, recall where that exact document is located, or try search field, the search field shows only garbage, search manually, enter edit mode, find paragraph to change, save document, go back to your code editor, try to get back to state of effective work), then documentation is just rarely (if ever) written.
I know that to some of you all of these things may seem a little odd. You know those tools, you use them every day without any problems, and writing documentation in general is not any different from any other typical task at work. Let me explain. In case of my problems with tool C… I believe it’s not only me.
Every time I stumble upon any discussions about it, people complain about exactly same things, and they are in majority (and this would be a simple Survivorship bias, if there wasn’t real bug-reports, closed with simple WONT_DO). In my team I was loudly commenting my problems long enough, to became a living joke… but then I started receiving from them screenshots and comments where they started noticing same, or other stupid and persistent problems.
For me you are lucky ones, if you don’t encounter all these bugs.
(And about struggles with documentation in general across industry, to some extent, similar observations are at the very beginning of The Pragmatic Programmer book’s chapter called It’s All Writing.
I just hope you trust me, that the point of this article is not an attempt to start another flame-war, but show to others like me, struggling with tools considered standards of industry, the problem might be not with them.)
I’m just finishing another article about tools, where I will try to present these, that I consider better alternatives.