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

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