4 Steps to Implementing Stellar Documentation

As a minimalist, I’m rarely excited to purchase things, yet I can’t help but share how awesome this KeShi foam roller kit is. Interestingly, the magical part isn’t the foam roller or the massage stick or the spiky ball you step on to cause infinite pain and gain…

The best part is that little booklet, entitled “User Manual.” Thanks to the pleasant blend of informative diagrams and concise text in the manual, I learned how to use the various tools to great effect—far beyond what I would have done on my own. I enjoyed going through each section, trying out the equipment in novel ways on body areas I didn’t even know I had!

Because the guide was so clear, I quickly and easily understood the value of the product. As a result of this delightful experience, I recommend the kit highly and have even sent a second set as a gift to my cousin. KeShi is getting a ton of business value from me without the need for any time or interaction from the company because everything is so well-explained in that neat little guide.

In the world of APIs, there are some well-known examples of incredible docs, for instance Stripe and Twilio. Like KeShi’s user manual but on a multibillion dollar scale, these docs have driven enormous growth for their respective businesses, from marketing and sales to support. Developers love useful API docs just as workout enthusiasts love clear diagrams.

Implementing great docs can be a massive undertaking. There are entire teams at Stripe and Twilio devoted to this. It’s likely KeShi required a serious investment to make all those nice diagrams and pull together a finished manual.

To guide implementation efforts, we’ll consider four key questions that are critical to successful execution. Let’s aim to maximize the usefulness of the resultant docs while minimizing the difficulties of implementation, and to ship early!

1. Who’s the internal stakeholder today?

We might be creating docs for an end-user, but there are likely intermediate steps that come first. Our manager or another colleague might review our work prior to launch, and it’s often useful to designate a friend as a quick informal step before any official review.

Suppose we have a project coming down the pipeline next week. We might think to ourselves, “I’ll do this project next week.” It turns out that rarely works well in practice, and such projects often bleed into the following weeks.

A much better approach would work backward, starting with a specific who: “At 3 p.m. Thursday, I’ll send a rough draft to grandma.” We might ask our chosen reviewer to bug us about it if they don’t hear back from us. We can send along a calendar invite. The goal is to make sure our work gets into someone else’s hands.

Trying to write comprehensive docs in a vacuum is really hard. If we want to have content that creates a smooth onboarding conversation with our user, then their initial questions and areas of confusion will be incredibly useful to explore as early as possible. We can’t get this feedback in a vacuum, so let’s put together a first pass and then talk to people!

We’ll also want to deliver micro-milestones to ourselves. Instead of fretting about a big ReadMe implementation, we can start with some easy wins. “I’ll spend 5 minutes right now creating an account, logging in, and maybe also pushing out a mini ‘Hello, world!’ example. Then I’ll take 10 minutes Friday throwing together a few page titles and headers to frame a rough outline.”

Trying out minimum viable workflows is a satisfying way to unblock future progress for ourselves. We sidestep the all-too-common sadness of discovering we’re unfamiliar with a critical publication process on the morning of an important meeting or demo.

It’s tempting to bundle all doc-writing into one big task, but that easily gets overwhelming. Just like developing the product itself, we’ll make better progress building our docs iteratively, by focusing on delivering version zero as soon as possible to an internal stakeholder.

2. How do the key features fit together?

Figuring out what we’re aiming for at the outset and nailing down the contours of the overall finished product will quickly get us very close to the finish line.

There’s a wonderful article on how to build an API from the ground up. The post talks about writing an OpenAPI Spec before writing any code, in the same way architects will draw a blueprint before breaking new ground on a construction site.

To write this blog post, I used my own little blueprint process before getting to any real writing. The first step was to brainstorm topics and ship a couple ideas to our friendly neighborhood blog admin, Shinae.

I jotted down a few different ideas, then selected my favorite and expounded on it a bit further. This took about 15–20 minutes. After thinking through the topics at a high level, I selected my best couple options and bounced these off Shinae.

With the topic in hand, it was time to generate a content skeleton. I filled out and modified my initial precursor outline for around 30 minutes by closing my eyes and typing whatever came to mind.  

From there, it was smooth sailing to flesh out paragraphs and insert connective tissue to create the result you’re currently reading.

3. Why do I need this?

We’re on our way. We have a clear stakeholder for whom we’re going to ship quickly. We have an outline in hand, a map that guides our implementation details toward a final outcome.

Now, it’s time to dive in and do the legwork. We have to write coherent sentences and draw useful diagrams. We have to format our page so it’s user-friendly, and we have to coordinate the colors to enhance our brand. We have to adjust the CSS to support tablets and mobile.

…Or do we?

The vanilla API reference on Hoot works just fine. Blend’s great docs use very little customization. We could invest a lot of effort to make a fancy custom search like Rapid7, or we could design a beautiful landing like Intercom, but it might not be something that our project needs right now to accomplish the immediate goal. Complicated widgets often turn into overhead requiring maintenance down the road.

When I said making this blog post was smooth sailing after generating a content skeleton, I fibbed a little. There was actually a major bump in the road when I initially wrote a 12-page essay and received feedback that we should cut the length to a third. Doing so was not easy but certainly worthwhile.

We can ask a manager colleague (or grandma) to help define success criteria if we’re not sure whether a paragraph, widget, or feature is essential. We should always start by sanity-checking ourselves to make something focused and simple, that just works.

4. What Should We Improve?

Once the essentials are in place, we might add a new color scheme or play with some fonts, margins, and button formats. However these changes are unlikely to be worth major investment of effort.

A substantial improvement might be trying out API logs and metrics to transform a static reference page into an interactive experience. Perhaps we could add example response JSONs to our OpenAPI specification or throwing in some server variables to tailor the words on each page to individual users. We could insert helpful pictures that take the place of thousands of words.

Users might feel delighted or robbed. Internal teams might cheer us on or pine for how things used to be. Either way, we know we’re doing impactful work when it’s engaging, challenging, and worth talking about. Great improvements come from bold steps toward something that might fail.

Feedback is welcome on this article, and we’d love to hear any tips that have helped you when implementing your docs! Many thanks to Vahid for valuable input and phrasings.

If you’re joining ReadMe on an Enterprise plan, we can support you with project management expertise every step of the way through your own dedicated customer success manager, for instance, the author. 🙂