The Seven-Action Documentation model – Fabrizio Ferri Benedetti

The Seven-Action Documentation model

Posted on Jan 9, 2025<br>· 12 min read

Table of contents:

I think all technical writers, at some point or another, feel the urge to base their work on something more systematic than “it’s just the way folks documented stuff since forever”. Toolkits and frameworks provide content types, which is immensely valuable when you know what you want to write, but starting from there is like buying a hammer without knowing that half of the work you’ll do is turning screws. As I find the lack of deeper conversation around this topic rather unsettling, I decided to contribute some verses.

Docs frameworks, tools, and formats aren’t enough

Most of the existing documentation frameworks focus on the actions of tech writers instead of focusing on the action of users, that is, the consumers of docs. 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? This apparent lack of flexibility disincentivizes writing the content that’s needed.

Some of those who designed docs frameworks are aware of this issue and have suggested that their rules are not to be followed verbatim and that there’s room for flexibility in their application to the real world. Writers who use those frameworks also faced this dilemma and, in most cases, ended up tweaking the models to suit their use cases. Frameworks thus become toolkits from which to cherry-pick templates and ideas. This pattern, though, evades the question of what’s needed.

Faced with the complexity of documenting fast moving products with little resources and support, writers will take everything they can and build a functional process out of it. Engineers dabbling in documentation and feeling lost as they approach the field, on the other hand, are drawn to docs frameworks because frameworks are all they’re used to working with when it comes to programming. The docs they end up developing are a cargo cult version of effective docs.

Shifting the focus from content types to user needs

A solution to this situation is shifting the focus from what should be written to what user needs should be addressed. This requires taking ownership of the strategic side of documentation (as in content strategy) instead of producing content following predefined structural patterns. Such an approach is fully compatible with documentation frameworks like Diataxis, DITA, and others, as it provides direction and purpose to the builders of docs, who’ll then use content types, elements, and tools at their disposal.

You can better understand how I think frameworks, tools, and models of user needs go together through a sandwich metaphor, especially if you haven’t had lunch yet: docs frameworks and tools are essential ingredients to holding a sandwich together and handle it, but what gives a sandwich all the taste and meaning is the filling, that is, the mental model of user needs that you’re following. This is not the same as external requests from stakeholders, though they might overlap. If anything, OKRs are the sauce.

In other words, to build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.

What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.

The Seven-action Documentation Model

The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.

As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve).

Notice that the order of the actions is intentional but not strict: I’ve arranged...