Understanding who you are writing for

You’re in front of the keyboard, and an editor opens with a blinking cursor. You have a brief and have experimented with a prototype. Now comes the task of figuring out how to explain that prototype to different user groups and profiles.

While reducing a discussion to an acronym may sound like a cliché, I typically start by thinking of the three Ws:

• Who is reading a document?
• What do they want to accomplish?
• Why do they want to accomplish it?

Even if you haven’t addressed these Ws, other members of your company likely have, and you can leverage their work in yours.

Your product, project, or feature possibly has multiple user profiles, and the type of documentation you need to produce can vary for each one. Functional user profiles are easier to break down and analyze, as someone whose job involves task A is more likely interested in documents that describe how to undertake task A rather than B. The level of complexity and the content are more subtle than this, and you can make some general assumptions based on the type of document someone is reading (I will dig more into what these different document types can be later).

Someone reading API or reference documentation probably has an idea of something specific they want to understand and know the functional facts. Someone reading a quick start is probably newer to a project and would like an opinionated introduction. Reference documentation and a quick start guide are two reasonably clear ends of the documentation spectrum. In between is the tricky part and the part where you will spend the most time.

If you are documenting a simpler project or a project with a focused use case, then this task is easier than something more broad and general purpose.

I appreciate that, as with many technical topics, everything depends, and implementation relates to the use case. It’s usually easier to follow with an example that walks through a thought process instead of talking in abstractions. So, let’s move on to a practical example.

Learning by example

For example, a geocoding library has far fewer functions and applications than a database or a programming language. Guessing what someone might want to do with any general-purpose tool is challenging and will take a while to perfect. Let’s take an example project used throughout the book. I assume that you are working on a greenfield project, but many of the same principles apply if you work on a pre-existing project.

Monito is a tool for monitoring application performance and errors. Monito comes in two versions: a self-hosted version where you have to connect it to your own backend and analysis tools to gather, save, and analyze data, and a hosted version that plugs right into a data store and dashboard service.

My recommendation is to start with the beginning and end of the journey and slowly fill in the gaps over time. Monito has two starter paths. There’s only one of you documenting the project, and time is tight. So, which should you document? Chapter 5 covers the full documentation process. For now, you get a strong indication that as much as the project wants to support everyone’s choice of integration tools, documenting all those possibilities will take too much time right now. So, you decide to start with documenting the hosted version.

To get started with the hosted version, a user must choose a software development kit (SDK) in their application code. Again, Monito offers SDKs for many languages. User research shows that the most popular are JavaScript, Python, and Go. So for now, you decide only to show examples for those but mention that other options are available.

The user then needs to register an account for an SDK key that identifies them as the user and instantiate the SDK with that key, so you show how to do that with the three chosen SDKs.

Next, you show how to trigger key events using the SDK in the three languages and how they appear in the hosted dashboard.

Finally, you summarize what the guide covered and point people to the next steps.

That covers the quick start. What about the reference documentation? For now, as a lot of interaction with the service is via SDKs and the development team has stuck to well-established best practices while building the SDKs, you decide to stick with autogenerated documentation from the SDKs. This is enough for those who want to dig into what else is possible after following the quick start.

A week or two after release, you start receiving user feedback. More users want to know how to self-host than expected, and many users want to integrate Monito with a popular alerting tool to know when it detects important errors. So, you need to document these two guides and any supporting material around them for your next priorities. The product team also tells you that they’re shipping a new feature soon that allows users to define custom data structures to send to Monito, and that also needs documenting and adding to the quick start.

Thus, the process is ongoing. You slowly fill in missing documentation gaps based on user requirements, product requirements, and feedback.

Don’t forget the end users and the end-end users

I have spent most of my career working on documentation for developer tools. So, this book’s focus is more geared toward tools others use to build products for end users. This means there’s an extra level of interpretation above the documentation I create that the reader interprets into another application or code base that might even have its own documentation. I like to call these users “end-end users.” While it’s difficult to guess what that end-end use case might be, if you can find out via support channels, it can help you narrow down use cases and user journeys when you want some semblance of focus.

Take the Monito example. Currently, the documentation covers general use cases for those incorporating the tool into their own tools. Through user research, you find that Monito has a large user base in the finance sector. This gives you a slightly clearer idea about examples you can use in code snippets and explanations.