Circles of Product Truth

Sep. 19, 2022

While thinking about unconventional technical communication, like comic books, children stories, and games, a thought occurred to me that they’re all attempts at hitting the core of what a product is and does, that is, its truth. I developed this picture of a series of concentric levels of comprehension and something resembling the circles of Dante’s Inferno came out of it. Don’t run away yet: Embrace hope all ye who enter here.

Picture a series of concentric circles, each focusing on a set of ontological questions. The outermost circle focuses on what exists and where, the intermediate circle on the hows and whens, while the innermost circle is exclusively for the raison d’être, the why. Now take the typical content types of technical documentation and distribute them over the circles. Something like the following would come out of that game of darts:

As technical writers, we often journey through different levels before getting to the core of what a product is and does. We start from reference docs and coordinates, slowly progressing into the jungles of practical usage. The closer we get to the core, the harder it gets to write docs, and not just because it’s less of a priority, but also because it requires deeper understanding, one we must scrape from the brain of stakeholders.

I’ve seen many product docs with a hollow core, but very few without the outermost ring. Sometimes, not even stakeholders know about the core of the product, a most disconcerting situation that content strategist know all too well: It’s impossible to document a product that doesn’t know about itself. Products unable to define their identity or mission in simple terms are hollow and doomed to aimlessly wander.

The moral of the story is that technical writers cannot realize the full potential of their documentation without getting to the core. Those who are already there, like founders or product managers, might know all about the why, but miss the truth in the outermost rings. Those trapped in the middle, mostly engineers and implementers, might miss both the outermost and the inner circles.

Much like Dante, it’s the tech writer’s mission to cross all circles and connect them.

Consider ye the seed from which ye sprang;
⁠Ye were not made to live like unto brutes,
⁠But for pursuit of virtue and of knowledge.

—Dante, Divine Comedy, Canto XXVI, Inferno