A large part of my day job involves reading and writing what folks optimistically call "technical documentation". It's usually about as much fun as sticking forks in one's eyes, rubbing a cheese grater up and down one's nose or reading the complete unabridged works of Ayn Rand.

Happily, there are examples of great technical documentation (the Django project immediately springs to mind, and the wonderful folks at Write the Docs do amazing work in this space). But for every example of great documentation, there are many more incomprehensible, incomplete or incoherent tomes where knowledge goes to die.

Joking aside, quality is clearly a subjective judgement.

It's easy to make innocuous claims like, "good technical writing is clear, coherent and engaging; bad documentation is the opposite ~ complicated, chaotic and opaque". Yet trying to pin down terms like "clear", "coherent" or "engaging" is a slippery exercise and, ultimately, a matter of personal taste.

A more nuanced approach would say diversity of voices and perspectives is at play here, and it's important to always keep this in mind. Every reader and writer comes to documentation from their own unique point of view and lived experience. That's why pointing out examples of allegedly poor documentation or claiming there is a "one true way" to write it is unhelpful. It's disrespectful of difference, arrogantly presumptuous and there are more supportive and open minded ways to engage when (inevitable) difficulties arise.

For instance, feedback that is constructive (offered from a desire to help), compassionate (aware of another's feelings) and unambigous (specific and actionable) can highlight unintended misunderstanding^[edit]. It acknowledges there is a difficulty of some sort, but does so in a way that encourages writers to reflect, refine and revise their work. It's also perfectly reasonable for the writer to decline to change things: perhaps you are not the intended audience, they simply don't have the time (many docs written for open source projects are created by volunteers), or they disagree with you and stand by their work.

Let many flowers bloom!

If I'm honest, I love to read (even stuff I find difficult or disagreeable ~ like Ayn Rand). It is a connection with others, a source of creative stimulation and an enlargement of my world. I read because I am curious to reach out beyond myself and into the lives of others. I love the change and growth this brings. I also love to write - it is an opportunity for self reflection, a source of consolation, an invitation to connect, and a rewarding skill to develop and practice.

That's why I write this blog: I enjoy the art of writing.

The artistry involved in writing is something to celebrate, cherish and promote. Sadly, and far too often, a focus on form, structure or process is held up as the best approach to writing technical documentation. Artistry, taste or style are hardly mentioned, if at all.

Most documentation looks like what most people think documentation should look like. There are good reasons why documentation is often organised in the way that it is, but to follow these conventions is not enough. Going through the motions in a structural sense or following a certain form or process is no guarantee of "quality" (whatever that might mean).

A wonderful and humorous example of this is Doug Zongker's "Chicken chicken chicken".

Originally created in the form of an academic paper, and then delivered in the form of a typical academic conference presentation, Doug created two parodies that focus on process, form and structure at the expense of meaningful content:

(I love how the audience all sound like chickens because they're laughing so hard.)

Doug's work got me wondering, would the "chicken" effect work for the tropes and conventions of a software project? I'm pleased to report that it does. It even works for the source code, Git repository and the packaging metadata too.

The "chicken" code highlights what a deeply problematic oversight this focus on form, structure and process is for technical documentation. Imagine if teaching the composition of poetry only dealt with structure, rhyme or rhythm at the expense of meaning, metaphor, story-telling, pacing, symbolism and expression.

We'd end up with limericks like this:

Chicken chicken chicken chicken,
Chicken chicken chicken chicken,
    Chicken chicken chick,
    Chicken chicken chick,
Chicken chicken chicken chicken.

Why this interest in technical documentation?

I'm in the midst of a writing marathon for some of my personal projects (Mu and CodeGrades). I'm enjoying the opportunity to reflect upon, and work both inside and outside, the usual conventions for technical documentation. I can't help but wonder that process, form and structure are best thought of as the servants of an authentic expression of thoughts, feelings and values through one's own authorial voice to make a space for the reader to think, engage and learn. If I am ever disatisfied with my output, it's usually because I've forgotten this (and I just had to write this blog post to say so!).

As always with any of my work, I welcome constructive, compassionate and unambiguous feedback. :-)

EDIT (18th Nov 2021): Thank you to the person (who wishes to remain anonymous) who reached out to point out that, "constructive, compassionate and unambigous", are also slippery terms. I've added clarifications in brackets and would especially like to point out that they embodied the very best of constructive, compassionate and unambiguous feedback in their correspondence with me. :-) Return to text.