When docs become performance art, everybody loses

You might have read Annie Mueller’s post poking fun at developers’ tutorials. If you haven’t yet, do it now. On the surface, it’s an exquisite rendition of the kind of technobabble we tech writers get to tame every day. Reactions among devs ranged from nervous snickering to outright shame. Like all the best parodies, Annie’s goes deeper than that, though: It puts a finger on “documentation theater”, a state where docs are performative and not addressing a need nor caring about it. Let me explain why I think writing docs because you are forced to is worse than not having docs at all.

I almost gave up but then I realized: If I connect the backside Snarfus stagnator to the backside shamrock Klingon troglodyte emulater, it’s good! Everything beep-boops and ding-dongs and I get the Actual Topic of the Tutorial, which lets me do the Very Simple Thing the way I want after all!

– Annie Mueller

Documentation theater, which I once called cargo-cult documentation, is the act of creating documentation for the sake of it, so that a box can be checked, an issue closed, or a project completed. Like bad fiction, tech comm is performative when it’s done to adhere to a certain form, criterion, or standard. And so README files are written because everybody has them, docs are released because there’s a legal mandate to do so, and so on. In the most nightmarish cases, entire docs sites are created following frameworks because that’s The Right Way™. We got to FAQ, right?

This doesn’t affect just docs; content strategists routinely pull their hair in desperation at the sight of performative content. For example, why does a restaurant website need an Our story section? Why should a resume contain gauges with fake skill percentages? Does your shop need a website at all? Doing things for the sake of can often be dysfunctional. In the case of tech writing, thinking that you’re creating docs when what you’re doing is dumping words into a file is particularly wrong, because docs have a moral obligation to solve needs.

If you felt hit right in the gut when reading Annie’s post, ask yourself these questions: What are you trying to say and for whom? Are you addressing a need? Is your content going to help the reader in any way? In The Seven-Action Documentation Model, which I wrote after reading the gazillionth comment on Hacker News blindly praising a framework as the Solution to All (as if encasing files in neatly split categories would magically make confusion dissipate), I argued that we should think of docs through the lens of user needs rather than content types, templates, or frameworks:

The prescriptive emphasis on what docs must be produced instead of describing what user needs should be addressed echoes an architectural mindset where one builds walls because of course a house must have rooms, what are we, barbarians?

Creating a tutorial aimed at beginners without knowing what the beginner thinks is an empty gesture. Consider any such tutorial in the wild: If instead of following the inviting form of a tutorial it had been written like an entry from a dev diary, it would have offered a more sincere experience, one that would have signaled to the reader that this content wasn’t really for them after all. You can deal with the curse of knowledge either by becoming a beginner, or by not pretending you’re talking to one (that’s why someone like John Carmack is honest).

Unfortunately, organizations often don’t care about the quality of their content (performative or not), and while they might have perceived the signs that they need tech writers, they might still ask folks to create documentation to fulfill a goal or satisfy their particular Definition of Done. Sometimes we can’t escape the script that’s being forced onto ourselves, but, while the fake author in Annie’s post has a cruel side in that it’s utterly devoid of empathy, you can choose not to be like it. This is the duty of tech writers: to uphold clarity and defend user comprehension in all situations where tech comms risk becoming faux.

We can help developers pick the right stage and fill their performance with meaning. When a dev hands you their draft, ask them: Who are you writing this for? Why would they care about your Snarfus stagnator in the first place? You can help them see that a brief conversation with an actual user (or even a virtual one, using Impersonaid) beats hours of guessing. Show them that the most honest thing you can write is “this is complex and will take you three hours” instead of “this is simple!” The script might be forced on us, but we get to decide how we’ll deliver it.