The annual North-American Write The Docs conference this May featured 2 API documentation redo presentations:
- Lyzi Diamond described Mapbox (formerly a part of Development Seed) documentation automagic in detail,
- Sarah Hersh talked about the journey that NPR One undertook towards a new task-based approach for their API’s developer documentation.
In this post we aim to give you an account of these presentations, plus a little extra takeaway.
Lyzi Diamond: Testing: it’s not just for code anymore
Lyzi Diamond from Mapbox showcased the use of docbox on their own documentation, through remark and retext. Lyzi showed why it works for them to test everything.
The story started in 2015, December, when Mapbox had a confusing TOC for their developer docs. They wanted the docs to be consistent, complete and correct, and contribution had to be possible.
The inner workings of the automation process
Their API documentation is in markdown, in a custom specified format which then gets rendered, tested, lintered into a human-readable output.
- The first batch of transformation happens with remark, a markdown parser that builds a syntax tree from markdown files. Based on predefinition, each syntax is transformed to be rendered in the left, right or middle column.
docbox (Lyzi Diamond, Mapbox)
Remark supports many linters and it also has built-in code generation. Remark is a free and open-source tool, well supported and documented.
- The second batch of automagic comes via Mapbox's version of retext, they use it to enforce linguistic correctness and consistency. Retext is an ecosystem of plugins that can do much automagic exactly to your custom specifications. For example: you can lint for simple typos or search for words on your no-list.
Overall perks for the whole team
The enforced structure and linters highlight inconsistencies in the original documentation and stimulate the various groups and roles in the company to talk with each other. Not only outsiders contribute: also insider non-coders now have a reference framework for pointing out when and how an API differs from the others on their platform. Furthermore: the rigorous documentation workflow brought group-wide understanding with it and asks for consistent decision-making and cooperation.
We got the directions towards the sets of tests (content-test, copy-cop, Hemingway app) and can start using them on our own projects. Thank you!
Sarah Hersh: Start with the tasks, not the endpoints
NPR One needed a developer center to enable the extension of the NPR One experience to new platforms and audiences, furthering NPR’s original goal of a more informed public.
Sarah illustrated task-based docs with a metaphor of the self-serving coffee shop: one conference attendee goes into a coffee bar in search of that first cup in the morning, potentially jetlagged. What they find inside is no staff but a wall of documentation: confusing and just too much information. What the customer would need at this point is to find clear steps getting her task done. The point is, accurate and relevant doesn’t equal helpful.
How do we define tasks? When you consider what the developer can do with your API, then the endpoints are the means and not the goal. Do the tasks align with the user, the API-owner’s goals and priorities? Before anything else, your team must be clear on why you give access to the API.
At NPR One, they defined developer personas:
- What is the persona’s role in their organization?
- What are they trying to accomplish? What do they want to find in the docs?
- How do they usually go towards this goal? Does this persona go through a typical problem-solving process?
- Do they have any known attitude/relationship towards the product or the brand in general?
Defining Personas (NPR One)
Ultimately, we need to know what developers are hoping to walk away with.
NPR One’s UX research and logged data analysis helped identify the common pain points, e.g. developers complained that they had to visit multiple pages before finding all the information needed.
NPR One prioritized the defined tasks. The team then decided to highlight the most common, so called umbrella tasks. They put the API reference as a separate main menu item for the more experienced developers but kept the rest of the documentation in a classic, shallow navigation structure under developer guide.
Developer Center (NPR One)
The new developer center received very positive feedback. As a result, the company introduced the task-based approach to other areas, such as the newsletter - which yielded 40% higher opening rates. The idea is to focus on what the reader might accomplish with the new feature rather than just presenting the feature as a new one.
Sarah provided us with a checklist for making our docs task-oriented, and a rinse-and-repeat example workflow to get it done.
Checklist for Task-orientated Docs (NPR One)
Andrea Longo showed the sysadmin’s perspective on software use and incident management, and although she was talking of software in general, one of her points is very relevant to API documentation: it is not only the end product (versions) we need to document. The reasons and data for our decisions along development can be equally important, at least for internal use.
Many other areas were covered by the speakers, the video recordings are on youtube.
