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 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