WtD Prague: API docs before the API exists

This week I’m attending Write the Docs Prague. It’s super exciting to attend a European Write the Docs conference, and to be visiting the lovely city of Prague. This post contains my notes from a talk at the conference. All credit goes to the presenter, any mistakes are my own.

Ben Ahmady’s talk was “Write the API docs before the API exists”. The topic was DDD: docs driven development. Ben works at a company that has an API consisting of RESTful endpoints. The users are developers and program managers.

The project

When Ben joined the company, they wanted to design version 3 (v3) of the API. To start off, they examined the problems that users were experiencing with the v2 API. They talked to product support and sales engineers, and looked at API logs and support tickets, to identify the pain points.

As well as identifying pain points, they wanted to make the API simpler to use: Simpler endpoint structure and request bodies, and default behaviour that was closer to user expectations.

Should a tech writer be involved from the start of a new project, at design stage? Ben pointed out that there are some disadvantages. For example, the design may change and the tech writer’s time thus may have been wasted. There are advantages too. For example, tech writers help ensure the design is consistent across different parts of the API.

Docs driven development (DDD)

The goal was to design a part of the API, and open it up for feedback in time windows. That is, provide a short period of time for feedback, then go back to design, and iterate.

They used GitLab for managing the docs (Slate) repository. Continuous integration (CI) was built in. Ben discussed some of the technical details. He also showed us the simplified requests that people can send to the v3 API.

Feedback on the resulting docs is positive. The team has also conducted some user research on the usability of v3. Some people find the docs important, but others prefer using Postman nearly entirely for experimenting with the API.


Overall, the project has been successful so far:

  • Feedback is good.
  • The use of GitLab CI and review apps has been very helpful, and will also be useful for future projects.
  • The docs are ready to go at the same time as the API.
  • The designers can focus on the whole experience.

Less positive aspects:

  • It’s still difficult to get feedback from users.
  • It’s hard to maintain v2 at the same time as v3. Ben has had to make the same change in each version of the API.
  • Sometimes it’s hard for people to see what’s changed, so the team has to describe the changes made.

Ben and the team are planning much more user research and further design iterations. They’re also investigating new ways of getting user feedback.

Ben has learned a lot about various technologies, such as the OpenAPI spec, testing in different languages, such as Java, and GitLab CI.

The takeaway for writers is:

Plan carefully, and don’t be afraid of the tech!

Thanks Ben for an enthusiastic look at a cool, exciting way of developing docs and API at the same time.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 17 September 2019, in APIs, technical writing, Write the Docs and tagged . Bookmark the permalink. 1 Comment.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: