A year of two into my technical writing career, I independently developed a research technique that I call the assertions document. It’s a sort of benign mind hack of the subject-matter experts (SMEs) that you’re working with on a given project.

An assertions document puts your initial understanding of the concepts you intend to write about in front of your SMEs as quickly as possible, and encourages them to actively help shape your project by getting them excited to correct you. This, in turn, improves both your understanding and your confidence in that understanding, leaving you in a better frame to start the actual writing.

The timing and shape of an assertions document

I write an assertions document after I finish my initial research into the technology that I need to write about, and before I have my first follow-up conversations with the SMEs about what I learned. In fact, the assertions document is meant to spur those initial conversations.

I aim to keep assertions documents conceptually simple, enough to let SMEs seeing one for the first time to quickly understand how they’re meant to engage with it. My assertions documents all open with a paragraph like this one:

This assertions document is a way to help me understand the technology I’m writing about. I make several confident-sounding statements that describe my nearest understanding of various facets of this technology, and invite you to correct me, or name some points that I am missing. This document is not a content draft, plan, or outline, and it does not necessarily reflect the final shape that the delivered documentation will take.

And from there, as promised, I proceed to bash out a bunch of assertive statements that match my best understanding about the technology that my writing project must address, as I understand them in that moment, and before performing any SME interviews.

Excite SMEs to help you by being wrong and incomplete

Critically, while I try to be as correct and complete as I can based on my earliest research and planning, I don’t sweat the details. This means that inaccuracies or omissions are very likely to be present—and that’s exactly what I want to happen, because that gives SMEs something to object to, presented in a short, easy-to-read document.

And a SME with a chance to catch you in the earliest stages of my project and tell me exactly how you’re wrong, or what crucial facets of the project you’re overlooking, is a happy SME, one who feels like an early investor in the documentation. Later, when your first complete documentation drafts are ready for tech review, an invested SME is more likely to feel eager for the chance to see how well their conversations with you influenced the final work—rather than dreading the review as another unwelcome interruption of their own responsibilities.

I have found such success with assertions documents that I usually deploy them instead of scheduling open-ended initial interviews with SMEs, the ones where you sit down with an empty note-sheet and say “So… what is this? How does this work?” This style of interview suddenly puts all of the burden of organizing a lesson-plan just for you onto the poor SME, and often makes them wish they were back in front of their code editor instead of having to explain literally everything to you.

If, on the other hand, I instead slide them an assertions document and make it clear that I welcome correction, I find that SMEs light up. Time and again, I have iterated over an assertions document with SMEs who are genuinely excited to see that I’ve begun the conversation with even a rudimentary understanding of the work that they’ve dedicated their professional time and attention to, and who are very willing to help me rapidly correct and expand the document until it seems complete and correct to all experts reading it.

With that thoroughly critiqued and approved assertions document in hand, I can then begin work on drafting the actual documentation, confident that I do so with solid conceptual footing. The draft, once completed, still requires a thorough tech review as usual, but the preliminary agreement over assertions significantly reduces the chance that reviewers will encounter major flaws due to fundamental misunderstanding on my part, requiring extensive rewrites.

A contrived example

Let’s say that I am assigned to document “Moocast”, an upcoming application my employer plans to launch soon. I have read its design specs and other internal engineering documentation, and had a chance to experiment a bit with the software first-hand. Time for some assertions! After starting a new document with the preamble that I shared earlier in this post, I start to bang out some statements based on my notes and impressions:

Moocast is an application for predicting the arrival of cows into a sphere centered on the user. It estimates time of arrival to within a ten-second window, and also reports the total volume of the arriving cows with 90% accuracy.

We offer Moocast as a free download for Linux and macOS. The application comes pre-installed on the Mootato™ detection hardware, which also automatically applies software updates as they become available.

Users primarily interact with Moocast through a command-line interface. It is designed to work with the separate. Its most important flag is --radius, which defines the radius of the detection sphere. The default radius is 100 meters.

Moocast works by detecting changes in the bovino fields along local ley lines. Customers do not need to deeply understand this in order to safely use Moocast. However, customers should understand the costs and limits associated with increasing the detection radius beyond the default.

Moocast works regardless of the gender or breed of cow.

And so on. If I end up writing a lot of assertions, then I might group them into several sections by header—”About Moocast”, “Operating Moocast”, et cetera—both for easier reading and as preliminary steps towards my own sense of information organization. Either way, my goal is to get into words the core points that I predict the documentation will need to get across, in the broadest strokes: No need for deep explanation, how-to steps, or detailed reference material.

And then I share this with my SMEs, and wait for their responses. They might say “The pickup geometry isn’t really a sphere, it’s more of a torus”, or “There’s been a delay: we detect only Taurus-derived breeds at launch, with support for Indicus planned for Q4”, or “I think our userbase prefers the term cattle over cows”.

I immediately apply this feedback to start iterating, editing the document and asking my SMEs to have another look. This continues until all parties agree that the assertions document contains only facts, and isn’t overlooking any crucial core facts about the product. And that’s when I start working on my first real, documentation-shaped drafts.

Happy hacking!

I joke that assertion documents are a psychological hack on your SMEs, but in reality they’re a confidence-boosting hack on yourself.

It can feel quite daunting to write authoritatively about a technology that you don’t completely understand at first! Ultimately, the assertions document is a tool to convince me, the writer, that I myself understand the fundamentals of the thing I’m writing about. When the assertion phase of the project is complete, then the SMEs’ approval of the assertions document stands as proof of my own qualification to write the docs, something that might very well have felt absent when I started the project.

I hope that this post has inspired you to consider this technique the next time you find yourself facing down a documentation challenge that rattles your confidence. If you’re anything like me, then meeting the technology by asserting your best understanding of it—and then inviting the real experts to tweak those assertions until they’re actually true—can help lay the foundations for your best work as a technical writer.