Write the Docs: Mark Tattersall – Documentation as a Product

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Mark wrapped up the conference talking about documentation as a product. Mark is a product manager at Braintree. There the API is, in a sense, their product. When he started there they had no getting started guides, no tutorials. That was the first thing he worked on and the first things he shipped.

We tend not to talk about documentation as a product in itself. We overlook it and lump it together with the product that it’s documenting and representing. It’s frequently relegated to a line item on a project plan; “We need to write the docs so that we can get this shipped.”

Docs thinking is somewhat tactical. You work through the tone and voice of your content, who the audience for it is, and the format it will take. Mark wanted to take a step back from the tactical, though, and look at documentation more holistically. We need to understand docs as something intimately connected and integrated to the product. You think about the problem first before jumping in to the ins and outs of creating a solution.

Product thinking is a lot about burning through a series of questions to get at what applies to your particular need. Those questions include:

What problems are the docs solving?

The fundamental question for any product. If you can’t understand the specific problem you must question what you’re doing in the first place. Your documentation has to cater to both existing and potential users.

Documentation is, in many ways, the analog to turning over a physical software box and reviewing the details of a product. Documentation can be the first enduring interaction that users have with your product. It acts as a reference and an index all in one.

Who will be using your documentation?

You can get at this by creating personas of your users. You don’t have to do this but it can be a great exercise; it’s something that they do a lot at Braintree. To do a good job of this you need to get out there and talk to your users. Talk to other groups within your company, too: support, accounting, marketing. Anyone who talks with your users is worth talking to.

When thinking about your users keep in mind that you don’t have a linear relationship with them. You don’t get to hand-hold them from A to B. They will choose their own path through your docs and dip in and out of the content. Users may even find their way there from any number of sources.

How should your documentation communicate with your users?

This is not a docs-only decision. You need to put it in the context of the company and the product set. Consider how your company talks with customers and what the product emphasizes. Find the voice and persona of your own product and make that shine through in your documentation.


What is the vision for the product you are documenting?

Where do docs fit in the grand scheme of things? You need to understand where the product and company are going. You want to make sure that your docs can handle the changes that are coming down the product pipeline. By establishing the core message of what you’re documenting you make it easier for users to orient themselves around that.

What does success look like?

Are your users achieving their goals when they are using your docs? They need to be getting answers to their questions and solutions to what they need. If you can, do a survey. Find data and information about the baseline for customers interactions with your docs. That lets you see what direction your efforts are moving the docs.

You can also look at funnels, analytics, calls to action, and engagement. Talk to marketing and other groups in the company. There are likely shared things you can incorporate in to your docs approach.

What do your competitors docs look like?

Learn from those around you and from different fields. Get plugged in to where people are talking about documentation and learn how to make yours better. After that research do different and do better. Don’t just mimic and mirror behaviors elsewhere; iterate on them and make them your own.


So, with those questions in place you can dive in to building your docs. Before diving in consider your information architecture. Consider your content, context, and the users you’re solving for. Let your answers guide your architecture; otherwise your content is at an immediate disadvantage.