Brendan Lynch - Blood, sweat, and creating an API handbook

API the Docs Virtual Event Series 2021 Recap

This talk was presented at API The Docs Virtual 2021 event series on 9 June. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Brendan Lynch

Technical Writer at ABN AMRO Bank N.V.

Brendan's presentation (video recording)



Brendan's slides



Creating an API handbook, from the perspective of dedicated documentation specialists and technical writers

API First

  • The value of APIs has been recognized and invested in, and it has been promoted heavily
  • APIs boost business: builds and promotes collaboration
  • APIs untangle IT: products and services are more flexible and easier to change
  • APIs streamline cooperation: the focus is on the customer by creating quality APIs, and developer teams have more autonomy when building API solutions

API handbook

  • Internal content which describes the API development process from A to Z
    • A single source of truth for the development and management of internal and external APIs
  • Multiple teams from different disciplines are involved: architects, internal and external gateway teams, standards, guidelines, and governance, marketing and promotion, internal development, security
  • Goal: To enable development teams to create APIs, so they don’t have to search multiple resources in different spaces

Process to create the API handbook

1. Agreeing on the content structure

  • Set up meetings with stakeholders (who are involved in creating and maintaining all the APIs)
    • Determine who the stakeholders are by talking to developer teams who have actually created and published an API
    • Talk to stakeholders as they became known and inquire about the points of contact before and after them
  • Agree on a structure to group the content: first plan is to use a structure based on the development process:
    • Design > Implement > Release > Manage

2. Agree on way of working

  • Define how the author-reviewer relationship would work
    • Technical writers are there to help to define structures, provide coaching if needed, complete reviews and offer feedback, and manage the content creation process
    • Authors are the experts of their area, have to write clear instructions of how a user would complete a task
  • Create task backlog
    • Maintain a Confluence page with test backlog table (with team, author, task status, action points)
    • Tasks can be broken down between the sections that are defined in the process
  • Define and set up weekly API handbook meetings with representatives from each stakeholder group
    • It can be decided who the right person was to write content
    • Set a timeframe of completion - authors have their own task to do, they are from different teams and this must be taken into consideration
  • Create a set of writing standards
    • Authors have a different way to convey content and different writing styles
    • Adyen's Technical Writing Style Guide: a set of writing standards based on Microsoft’s Writing Style Guide and Google’s Developer Documentation Style Guide
    • To help with consistency
  • Provide training on technical writing
    • Make presentations from the Guide, provide trainings for authors and their teams
    • Consistency improved the writing

3. Manage and review author tasks

  • Keep track of task status
    • Update and maintain the task backlog regularly
  • Provide technical writer review
    • Give detailed feedback to explain why a change or edit is needed
    • Feedback through inline comments and compliments
    • Schedule meetings with individual authors to discuss bigger changes
  • Attend and chair weekly API handbook meeting
    • Someone is always responsible to steer the meeting into the right direction
  • Set time expectations
    • An open timeframe could lead to the test never been completed
    • If people are committed to a timeframe in a meeting, they are more motivated to do it
  • Maintain task backlog
    • Send the updated backlog to the teams after each weekly meeting

4. Test, release, and obtain feedback

  • Read out-loud tests
    • Developers who are not familiar enough with the topic go through the process while sharing their screens
    • You get to see how each section is processed by the tester, and can get instant feedback from the user
  • Provide access to users (Release)
    • They can provide feedback in the comment section
  • Reach out to author teams
    • Authors and their team can monitor the incoming feedback, take actions and edit the incorrect sections
  • Collect feedback from users
    • Gather and reorganize by section
  • Ensure content is up-to-date
    • Notify authors about the feedback
    • Organized feedback can help them keep the content up-to-date

5. Refine processes and structure

  • Based on feedback, moved to a process oriented structure
    • It seemed the users still find it difficult to navigate and find the information they need
    • “I want to do X. How can I do it? What are the steps?”
  • Create content architecture map
    • What do users come to the handbook for? A content architecture map can help to visualize it and define the the main topics
  • Define the main processes (use cases)
    • Create a new API
    • Update a released API
    • Retire an API
  • Define and implement content reuse
    • It is difficult to structure the large content in an intuitive way
    • Instead of repeating and copying content in different places, Confluence offers an excerpt macro with which you can insert content in single pages that can be then displayed multiple pages
    • Create user flows so that users are directed to specific pages depending on what they want to do
  • Specify and determine process owners
    • Provide contact details at the top of each section so users can get relevant support
    • Process owners are more motivated to ensure their content is understandable and up-to-date so they do not receive too many support messages

Future improvements

  • Move content from Confluence to MD
    • Static site
    • Review as Bitbucket pull requests
    • Pipeline for publishing
  • Create an integrations handbook that includes:
    • REST APIs
    • Batch
    • Streaming
  • Review and improve content regularly

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.