by laura / 1 June, 2017

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... Read more

by laura / 23 February, 2017

The UK kernel of the Write The Docs community together with the Government Digital Service held a one-day mini conference on the practice of agile documentation.

In his presentation Rob Woodgate gave us a half-hour distillation of his insights on where technical documentation stands with agile development methods. He wrote several articles in the past years on the mythical nature of the multi-talented developers, around the definition of done and the situation of doc writers in a scrum development team.

"I've seen very few teams that are actually agile, where everyone is able to work on stuff all in the same time, where you get up and down in that circular effect. It does tend to be a series of mini-waterfalls."

In theory, everyone in the scrum team pitches... Read more

by kathleen / 23 November, 2016

Self-service support is arguably the most important role of a developer portal. Without proper documentation, API teams will spend countless hours on introduction workshops and other training and support efforts.

In this post we’ll analyze the characteristics of a number of support resources and look at how they involve users to develop information about the problem areas in an API’s use. We’ll list pros and cons for the different resources, look at their place in the site architecture, and finally propose best practices.

Support resources are a documentation format

Even the best documented APIs, that complement their API reference with plenty of onboarding tutorials, also have a wide range of support solutions on their developer portals. Twilio, often praised for the... Read more

by kathleen / 17 November, 2016
Reference pages: an API’s inventory and checklist

Once a developer knows how to use your API, they will need detailed instructions on how to build the actual integration. Experienced developers already familiar with an API, including its creators, will have a hard time completing an integration without access to the API reference. That is why developers will often refer to them as “the API documentation”. This is a dangerous practice, as it implies that an API reference would be the only documentation an API needs, we talked about this in our previous posts.

In this post we’ll show how the developer portals in our research sample implemented their reference pages, compare their formats and labels, and try to deduct best practices you could apply on your developer portal.

... Read more
by kathleen / 2 November, 2016
Guides and tutorials: documentation for differently skilled developers

If the primary function of a developer portal’s onboarding page is to help developers self-select their knowledge level and to create an expectation of learning, then the function of the guides and tutorial pages that are linked from an onboarding page is to fulfill this expectation: to design an experience that will be as close as possible to the learning requirements of key audience segments.

In this post, we will explore how the sites we reviewed included guides and tutorials in their information architecture, we’ll look at what they covered, and finish with listing what could help to maximize their effectiveness.

Sharing theoretical and practical knowledge

Guides and tutorials are not always... Read more

by kathleen / 21 October, 2016
The onboarding page, a crucial component for developer portals

Developer experience on first contact is arguably the single most important job of a developer portal. In some cases your API might only have a few minutes to hook a developer, if it isn’t immediately clear where developers can start their integration efforts, they might leave and never come back. This is why onboarding pages are so important. In this article we’ll list the various roles onboarding pages need to fulfill. We’ll also explore how the developer portals we reviewed expose them and how they are labeled.

Different onboarding for different audiences

Depending on the objective and the prior experience of a user, an onboarding page needs to fulfill 3 different roles:

Evaluate: Help developers and... Read more
by steve / 30 September, 2016

This blog post is based on the presentation with the same title that I gave at the Write The Docs Europe 2016 conference on the 19th of September in Prague.


As a beginner content creator, I had hard times during my work.

Most of this because of my lack of confidence and practice. To grow faster, I had to build a process (rather a daily routine) that I could follow at work. I had to find the most effective supporting tools and maybe most importantly: I had to figure out how to keep myself motivated despite every failure.

This blog post is about my methods for becoming a better writer in English. It shows my tricks for self-improvement. I don’t want to pretend I have accomplished my goal: I’m still on the road and I have a lot to learn. But I hope... Read more

by kvantomme / 21 April, 2016

The video recordings of the lectures held on the Documenting APIs mini-conference are now available on our dedicated event page.

On March 4, 2016 we helped organise a special whole-day meetup in London on the Write The Docs conference, in which the community discussed the tools and processes used to document APIs.

We recorded the sessions, mashed them up with tweets and summaries and published them.

On the page you will find the following content:

James Stewart, Director of Technical Architecture at GDS: Intro and welcome to GDS Rosalie Marshall, Tech Author at GDS: Understanding the needs of API documentation users Ellis Pratt, Technical Communicator and director at Cherryleaf: Aye, Aye, API - What makes Technical Communicators uneasy about API... Read more
by kvantomme / 19 February, 2016

The first week of March I will be in London for 3 events related to documentation, APIs and Drupal Developer portals. If you are working on an API documentation project, you should not miss this opportunity:

I Love APIs - Wednesday March 2nd

A one day event organised by Apigee. "I love APIs Europe brings together European digital leaders who will share their strategies and lessons learned, combined with hands-on educational sessions led by the world's most experienced API Ninjas."

Buy your ticket here

Developer Portals in Drupal - Thursday March 3rd

A free half day workshop about Drupal Developer Portals with Apigee (whose Developer Portal is built in Drupal). On the agenda:

What is Drupal and why is it a good platform for Developer Portals (Kristof Van... Read more