Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Write the Docs Before the API

Ben A
September 16, 2019

Write the Docs Before the API

This talk proposes to discuss a recent experiment we at Onfido undertook which took a novel approach: "write the docs before the API exists".

Ben A

September 16, 2019
Tweet

Other Decks in Technology

Transcript

  1. Ben Ahmady - Write the Docs Prague 2019 @superdevx (Twitter)

    ben-superdevx (GitHub) Write the Docs Before the API
  2. This talk • Onfido’s Developer Experience (intro) • Our new

    API (v3) • Docs-first approach • Feedback • Positive outcomes and lessons learned • Bonus: “Involving tech writers from the start?”
  3. Onfido’s “Developer Hub” • JSON API consisting of RESTful endpoints

    • “API reference” documentation (Slate, docs-as-code) • Quick Start guides • Postman collection • Client libraries • Also: Mobile and Web SDKs (GitHub)
  4. API v3 wishlist we started with • Start with research

    into v2 (pain points, quality of integration) • Aim for improvements to experience, rather than “step change” • Release when it’s ready • Client libraries from OpenAPI
  5. Make things simpler • Endpoint structure • Request bodies •

    Change default behaviour to what users expect • Simplify the documentation itself
  6. Docs-first approach Original idea: “Let’s document an ‘ideal’ version of

    API v3, before we actually make it, and ask for feedback?” Evolution of idea: “Let’s stagger our ‘ideal’ changes to the API in a docs instance, and ask for feedback.”
  7. Docs-first approach First-time, new experiment at Onfido (2 people, some

    crossover) Alan Carrie, software engineer: API v3 development, reviewing and working on docs Ben Ahmady, tech writer: Documentation + setup of instance, OpenAPI, Postman collection
  8. Team structure • Agile (Scrum) • “Developer Experience” tickets part

    of 2-week sprint • Tech writing part of Product org, but sits with devs • Maintain docs-as-code approach
  9. Docs-first approach (API v3 micro-team) • Weekly meetings to discuss

    changes • Establish docs instance workflow • Open docs up for feedback (in “time windows”) • Make changes to the API itself after feedback windows close
  10. GitLab CI • GitLab for managing docs (Slate) repository •

    CI built in • New branch for v3 • Part of CI: builds new instance per-branch (‘Review apps’)
  11. Workflow 1. Push proposed changes to branch 2. Changes deployed

    almost immediately to internal domain 3. Advertise the ‘Review apps’ deployment on Slack 4. Ask for feedback 5. Scrum: make changes (API, OpenAPI spec, Postman collection) 6. Repeat
  12. Feedback In quotes: “Much better than the alternatives” “Really easy

    to keep track of changes” “Great, but hard to see exact changes at times!” “Very good, but I already am familiar with it”
  13. User research (on using API v3 with docs) • Internal

    new joiners - so far • Focused on usability of v3 • Docs are important, but some prefer Postman nearly entirely (justifying additional focus) • Some very obvious fixes to make to improve testing
  14. Positive outcomes (pt 1) • Success: https://documentation.onfido.com/v3/ • Good feedback

    we would have otherwise missed • GitLab CI / Review Apps huge help - not just for this project • Process useful for us as much as for anyone else
  15. • Docs ready to go when API is • Content

    debt not an issue • Far easier to manage aspects like OpenAPI, Postman • “API designers” - could focus on whole experience Positive outcomes (pt 2)
  16. Lessons learned • Engagement still as hard as ever •

    Hard to maintain v2 docs changes at same time as v3 instance • Sometimes needed to describe changes • Relied on Slate instance being stable enough
  17. Next steps • API v3 full release imminent • Total

    Developer Hub design makeover • GitLab “Visual Reviews” • Lots more user research and iterations
  18. Involving tech writers from the start…? “You don’t have an

    API if you don’t have documentation.” “Needs documentation to be feature-complete.” Question moot if you don’t have tech writers!
  19. Involving tech writers from the start…? Advantages • Content debt

    not an issue • Closer to other parts of the business • Better sense of user expectations • Consistency within design
  20. Involving tech writers from the start…? Disadvantages • Projects change

    - sometimes dramatically • Scepticism about value of dedicated docs writers • Differing expectations • Access to developers
  21. Involving tech writers from the start All depends on project

    (and people) In our case, very successful: • Strong, positive review culture • Agile (Scrum) workflow • Investment in project
  22. Personal development bonuses For tech writers on the techy side:

    • OpenAPI • Testing in different languages (Java, PHP) • GitLab CI