<rant>
“Documentation”.
As I speak the word out loud, the conversation dies down.
It’s that dead thing. That thing I don’t like writing. But I have to anyway.
Coding is fun! I make stuff. I mess around, often clean it up too.
Then — ugh — there’s writing docs.
I don’t even remember what I did. Well, I remember parts of it. I can write that. I type it up quickly, and close my text editor as soon as I write the final sentence. Done. Not looking at that again. I swear to myself — next time I’m writing self-documenting code.
I’ve had some of the weirdest conversations in my life when the topic of documentation comes up. I like writing things down. In fact, I find great utility in writing things down. My writing extends my mind.
Without writing things down, I either have to keep lots and lots of moving pieces in my head, or lower my expectations.
Instead, I choose to cherish my expectations and explore my taste. I that process, I write things down. My notes are not output. My notes are my thinking.
When working with others, I sometimes get a feeling that we’re following a track towards confusion and vagueness. That’s when I want to start writing things down. To me this makes sense. Written text has played a central role in every good thing I’ve made. But others might have a completely different working process. They think I want to start producing “documentation”. And “documentation” is defined by something like “extensive written text that’s tedious to write”. Which is the complete opposite of what I want. I want to improve perception. I want to enable us to see better, so that we can create better.
Can documentation be good?
I can find the act of writing documentation to be an enjoyable experience. It’s so close the intent of Intent, Relationships, Action.
I approach documentation in the same way I approach code — through Feedback loops, interface design and how stuff works. I write documentation as the interface between my understanding and your understanding. The feedback loop tests how well the documentation explains its topic. Can you understand what you’ve written yourself? Are you happy with what you’ve written? Can the documentation you wrote successfully explain the topic to someone else? Do others find your documentation, or repeatedly ask the same question? And has anyone ever read the whole thing you wrote?
It pains me that we strive to produce great code, but when it comes to documentation, we’re content to slap some words on a page and never look back. In one sentence, we preach continuous delivery, continuous integration, and caring about working code, as the old timers of the Agile Manifesto would say. In the next, we see a fellow dev struggle with complete disorientation, and we turn our backs on them. “oh, it’s just docs.”, we say, and write more code.
why care about documentation?
Because understanding how to structure knowledge properly turns situations of total confusion into interesting design problems.
Who knows what? Who needs to know what?
To me, that shared understanding exceptionally important.
I don’t want us to have an okay-ish agreement about what we’re doing. I want us to have crisp shared intent.
Because that’s our mind. That’s how we work. That’s our strategic process — or lack thereof.
the article is over - keep on reading or do something else at your leisure :)
comments
2022-10-08 Erik (Teodor paraphrasing): there was this library I remember using. Its docs were amazing. I’ve read references. Like, when you have a list of all the functions and docstrings. Lots of detail. But there was this .NET libary called triangle.net. They just had a list of examples. The first example was easy. Then each example introduced gradually more complexity. I liked that one.
https://github.com/garykac/triangle.net/tree/master/wiki
2022-10-09 Oddmund (Teodor paraphrasing): Perhaps a good metric for “is the documentation working?” is measuring when the docs are read?
2022-10-10 Richard (Teodor paraphrasing): Perhaps a good metric for “is the documentation working?” is the amount of questions asked on Slack? Or perhaps the amount of repeated questions?