Smith, Sage, Sovereign: Writing Technical Docs That Make Heroes

People think in terms of stories. We construct narratives of our lives, both lived and idealized, and attempt to rationalize the ebb and flow of our experiences in a chronological order that makes our success and failures part of our narrative of growth. We tell ourselves "we aren't what we were yesterday" and, in our better moments, admire our progress in the face of...well, all this complexity. Stories are the chronicles of struggle and change, and often of learning and growth itself.

As technical writers, we type words, but we don't always consider that we're telling stories. The notions of chapters and volumes have receded as the web became the main avenue for publishing technical content, and we think about "nodes" and "parents" in nondeterministic graphs, reducing the act of learning to the sort of effort that wouldn't be out of place in a CS 201 text book. Oh, we frequently discuss "how the customer got to that page" in terms of constant surprise, and while we are aware our customers are each on their own journey of learning, we don't respect it — we're too caught up in the details of any planned or current page, and the "what has come before" and the "what will come later" are afterthoughts, arguments to be had in meeting rooms without any common or shared sense of a greater customer narrative to hew to.

And so we do the same thing over and over: we ship the bloody org chart. We wring our hands, we recriminate, and then we do it again because the alternative seems like more endless hours spent on calls with customers and support engineers, trying to inductively winnow some common thread of the customer experience, like the poor bobby about to receive a major flex from Sherlock Holmes at the crime scene.

Put on your tweed and houndstooth cap for a minute. We talk about journeys ad infinitum, trying to map incidental feedback and knowledge with empathy and care, only to fall short when the numbers are reviewed. And yet, we're not talking about the nature of the customer journey itself — the core notion we all accept and embrace but disrespect by trying to construct it haphazardly from the artifacts we can scrape together.

Seriously, people! So much has been written by our English major friends about the narrative of a journey, about the ubiquitous concept of being a hero. It's a total cliche these days, yet likewise fuels our imaginations and the most popular stories we tell even in 2024, from endless Star Wars sequels to the rehabilitation of classic myths. These stories, at the very least, give most folks the good brain chemicals and advance their drive to take action. And even though tech writers are known for their terse and clinically precise prose, our readers still want those good chemicals. In the throes of last-minute enterprise migration meetings or when trying to debug that last bit of Python, our customers would like to be a hero.

So, uh, maybe approach technical docs as a "hero's journey" as a first principle? If you want someone to understand what it means to be a hero and have the chance to feel like one, use the most common and time-tested narrative model out there: the Hero's Journey, as articulated by Joseph Campbell (abbreviated):

In its most elementary form (as a monomyth), a hero goes on an adventure, emerges victorious from a defining crisis, and then returns home changed for the better.

Now, it's not the words themselves that can make a customer feel heroic. It's the narrative structure -- the specifically chronological flow of content that flows as the protagonist develops from a state of innocence and ignorance to a future of strength and wisdom, propelled by a desire. If that desire flags through obstacles and conflict, the hero must be supported in some way. All hero archetypes possess some measure of will, but in the face of their journey's darker moments, support arrives and their will is refreshed to push onward.

We, as writers, have a role to play. We are NOT the narrator — every journey is unique. Shed that hubris. Rather, through our privilege and experience, we step into many roles as we craft content: the blacksmith who takes the hero under their wing and teaches them the basics of steel and survival; the wise woman who shares her lantern and guides them through the treacherous forest paths and the lore of ages past; the court advisors and trusted leaders who offer informed opinions and point to the roads of victory.

We are potentially significant characters they encounter on their journey, nameless as we might seem to them. WE MUST ADVANCE THE PLOT.

And we do that by structuring our content so we can be found and thus advise them. We guide them into and through the Hero's Journey. Done correctly, we craft their destiny. We can create heroes — what a wild thought, yeah?

We can start to craft destinies by simply planning content that respects the Hero's Journey. It's 3 simple acts, which I'll describe below:

Act I: The journey begins. All heroic introductions start the same way -- the impulse to break free from some limitation and to seek something greater: glory, revenge, riches, success. We don't care about the hero's motivations; we just care that they are ready to act. But directionless action is the first potential failure state in any journey that isn't an absurdist farce, and I'd venture to say that's what docs without a strong Act I component quickly become. (Sorry not sorry.) You must prepare the reader, and you must prepare them quickly. The Dark King's men might be at the gates. The VP might want that new feature in production tomorrow. Act I is by necessity short — it takes the hero's volition and puts it into motion so the journey can begin. Consider the trope of "Get started" material in tech docs: we KNOW we must have it, but so often it is the sum of any journey in technical docs. "Okay," you tell the reader, "you know what the UI looks like. You know how to make a couple of simple API calls. Good luck and well wishes, friend!" (Later, the reader is eaten by a wolf.) They needed more than a couple swings of the old sword, I'm afraid to say. They may have needed a map. They may have needed a review of common monsters in the forest. They may have needed a few more techniques. When constructing "Act I" materials, ask yourself: what is the journey ahead, and what are the things they need to traverse it? They don't need everything; don't fill their backpack with trinkets and tomes they'll never remember you gave them. PREPARE THEM FOR ACT II EXPEDIENTLY. And to do that, you need to understand what will happen in Act II, and this is where most technical docs drop the ball...

Act II: Into the forest. The reader-as-hero may be quite confident if Act I passed quickly and effectively. You know their confidence is a lie, as the specter of Dunning-Kruger hovers like a dire shade over the proceedings. The first taste of the real world outside the village (and its simple sandboxes) lies ahead, and it is a dark and vast forest of technical complexity and options, populated with its own delights and terrors. A haphazard journey through it may be successful, but there WILL be demons, and the few survivors are scarred and bitter and likely to slag your product on social media. Or, if they're a benevolent soul, they'll share their post hoc learnings as guideposts in your communities, usurping your narrative with stories of their own. YOU MUST JOIN THEM ON THEIR JOURNEY. Your role becomes a new form of mentor: a dubious sage who knows the forest and its myriad paths and destinations, and who will endeavor to coach them at every crossroads and rescue them when they meander into dark dens and hidden snares. This is where opinionated tutorials that expressly follow Act I matter the most, as well as clear troubleshooting guides, visually oriented conceptual content, and a panoply of curated reference topics. These materials can and will save the day, over and over. You can't guarantee the hero's triumph during the most critical stages of the journey, but if you understand the roads and can anticipate the hazards for them, you can BE THERE FOR THEM. Gandalf grew from his experience despite his years and painfully accrued wisdom, and you will too because this isn't just the most critical act for the reader-as-hero, it's also for the writer-as-sage. You will also learn what you don't know, as you listen to feedback and iterate. This is the hardest content to plan, structure, and write, and that's why it's rarely found in any strong form among the countless sets of technical documentation I've read (and shamefully, written myself). As a writer, you don't need to be a god, but you do need to play the part of a hierophant that can anticipate the paths the hero will choose. That means you'll need to go into the forest yourself, over and over, and map it out to the best of your abilities. You need to start better than the hero and end with them as at least your equal in knowledge of the space you're documenting. And you can never let your empathy go. When they can credibly hang with other heroes, hang up your lantern and follow them into the last stage of the journey...

Act III: The kingdom awaits. You have quickly trained the hero and guided them successfully through an adventure. They have defeated the dread specter of Dunning-Kruger and now, humble and aware of their undertaking, see the kingdom before them — a kingdom made of product features that is vast and often uncharted, waiting for them to adventure freely and develop their own stories at last, armed with knowledge and girded with credible experience. They know what success looks like, they can anticipate pitfalls, they can grapple with debugging and esoteric configuration formats and awkward UX. Now they just need to know what the options are, because Act III is entirely their story, and you are a trusted advisor. You will not join them, but they will return to you with questions: questions you answer with complete and up-to-date reference materials, deep examples, and reports on the status of the product as it changes. Your journey is over, while theirs has truly just begun. And done right, you will be respected. Gandalf may have been a bit of a prick at times and made some off calls, but ol' Frodo and Aragorn alike know he's a major part of the reason Sauron ain't around to ruin everything any more.

And wasn't Gandalf a hero, too? Heroes often teach other heroes. Your journey in crafting great documentation -- all the research, the experiments, the conversations with friends and foes alike, the failed efforts -- is likewise a journey of learning, one you repeat time and time again to better create and support heroes for the product you document. You dive into the forest over and over, suffering wolves and uncovering treasures, to tell this tale and through it, shape destinies. I don't see why we shouldn't embrace this narrative model, or perhaps we do, but don't reliably respect it across the countless days of endless Jira tickets, constant feature and UX changes, and shifts in marketing strategy.

Sherlock Holmes was a hero. He became one by applying first principles and wielded the instruments of logical deduction, rather than frustrated inductive reasoning. He saw patterns and correctly placed evidence within them, ultimately realizing a narrative that explained everything. Shouldn't we be like that, too; to take the Hero's Journey archetypes and populate its simple pattern with intentional navigation and content that answers the reader's request for insight and success? To make them a hero, too?

In technical documentation, allegories and metaphors are deeply discouraged on our pages. But in crafting good content architectures and narratives, they are essential. They are the distillation of human experiences over time. I think we should embrace them more in our content planning, rather than relying on endless refactored formulae and templates and conventional wisdom (often coded as dogma).

Certainly, be a technical writer. But also, I'd say, be a technical author, a crafter of tales. Make heroes and become one yourself by engaging with their tales. Leverage the Hero's Journey and keep the focus on Act II, because that is where we seem to reliably fail. By acting first as a humble smith, then as a guiding sage, and finally as a consulting sovereign, we become a real character the reader has an implicit connection to, which is at least a helluva lot more interesting than being another hopeless NPC in a customer's tale of tragedy.

“To translate knowledge and information into experience: that seems to be the function of literature and art.” - Joseph Campbell