Sunday, 17 July 2016

On documentation and audiences

In this post, I'd like to make a short plea for better product documentation.

One of the entry points to the Cronofy API documentation has an explicit link "for Product Managers". This link takes you to their use cases page. Over the past few years, I have looked at plenty of API documentation. From PDFs to the current trend of a GitHub repository and wiki. This was striking in how unusual it was. But if your product is an API then why should it be?

In the technology service industry should we go further? Should there also be a "for testers" link? This could be like the Cronofy Product Managers link. It could reuse existing information but highlight and target them for a specific audience. For example, take the developer sections about rate limits and validation. Then add testing tips about your API for integration testing.

Stripe has good developer documentation. Yet you have to scroll down a couple of pages of information before reaching the words "Not a developer?". Although one major plus point is that it does explain what the API does by then. This is often seen as a bonus. For example, the blog for Launch Any lists it as number 11 in 10 Questions Your API Documentation Must Answer.

The examples of good API documentation over at Documentor are clear. But they lack a certain humanity. I believe that documentation deserves the same kind of tailoring as marketing literature. That we write with empathy for the audience. Good marketing copy does this. It builds a bridge. It relates the product to the reader and their concerns. Shouldn't we use the same skills to inform? If we are already using them to persuade and sell.

Adventures with flow and transparency

Photo by  Sasha • Stories  on  Unsplash This is a follow up to my post on roadmaps and themes . I wanted to talk about experience in a B...