This article contains affiliate links. See my affiliate disclosure for more information.



Docs can make or break a product.

Documentation is the second most important factor developers use for deciding which database to use, according to the 2022 State of Databases survey. And in an informal survey at the 2017 SciPy conference, respondents felt, on average, that developers should spend about 20% more time on documentation.

End users know docs are important. Developers know docs are important. Why does it feel like good docs are so hard to find?

In part, it's because docs are so often organized by who the user is and not how they use documentation.

✉️
This article was originally published in my Curious About Code newsletter. Never miss an issue. Subscribe here →

The Wrong Personas

I work for a database company. When I think about our users, I think about:

  • Software engineers
  • DevOps engineers
  • Database admins
  • Data engineers
  • Data analysts
  • Data scientists

...and so on.

It's a natural approach.

But after participating in user testing sessions for our docs website, I'm convinced basing personas on roles is the wrong approach. A user's job title provides no information about how they will use documentation.

Pay attention to how users interact with docs, and you'll begin to see patterns emerge — patterns that are way more useful than job titles for planning and organizing docs.

The Three Personas That Count

How I use docs hasn't changed much over the years.

I like to build a mental model first. I read through any introductory material, follow a tutorial if one is available, and run a few examples, all before I start to solve whatever problem I'm working on.

Not everyone is like that.

In a brief published in the 2007 Dagstuhl Seminar Proceedings, Steven Clark discusses how observing software-engineer end users (think end users of APIs and SDKs) for a year at Microsoft led his team to develop three personas:

  • Systematic developers prefer to understand the technology before they use it. They tend to code defensively and seek elegant solutions.
  • Opportunistic developers are primarily concerned with solving business problems. They seek practical solutions and are more willing to experiment with a product without consulting documentation.
  • Pragmatic developers fall in-between systematic and opportunistic developers. They code methodically, seek robust solutions, and tend to use documentation alongside exploration.

I'm a pragmatic developer. Which one are you?

In a 2019 observation study, researchers at the Merseburg University of Applied Sciences noted that "our classification of participants as opportunistic or systematic developer does not seem to predict general programming experience or the availability of domain-related background knowledge."

That's consistent with Clarke's own observation: "The work styles we described in the personas are shared by people with varying levels of expertise and educational background. It is not the case that someone starts out as an opportunistic developer then becomes a pragmatic developer after gaining a certain level of experience and expertise."

It's consistent with my own experience and observations now that I'm paying attention to how people actually use docs.

I've been writing for the wrong personas the entire time.



The Impact On Content Design

Good documentation builds on a foundation of practical, self-contained examples.

Pragmatic and systematic developers will use longer documents, like tutorials and concept guides. But opportunistic developers have little interest in reading a thousand-word explanation.

A solid example offers a good entry point for all personas:

Opportunistic developers can experiment with and extend the example to quickly build solutions. Systematic and pragmatic developers can use the example as a foundation to explore more about the product and build their understanding.

A good example:

  • Is self-contained: the user can copy, paste, and run it without error, setup instructions are included or clearly linked, or the user can open the example in a hosted environment.
  • Is practical: it shows a real situation the user will encounter and can easily be adapted to other situations.
  • Warns the user of any gotchas: it includes important information about behavior that might be unexpected or guidance for deciding between multiple ways of doing something.

Opportunistic developers may never look beyond an example. Providing clear links to further resources can satisfy pragmatic and systematic developers without smothering opportunistic developers with too much information.

And even though these three personas are better for figuring out how to organize and present information, the old personas — the ones organized around job titles — are still useful.

They inspire the entry points.

Want someone to use your docs? Find a good first example targeted to their needs. Make it self-contained so they can use it without friction. Provide generous links to more resources.

Then make that entry point easy to find.

Dig Deeper

Learn from the collected experience of several industry veterans in this thorough and thought-provoking book. It's essential reading for all developers.

Available from Amazon.