Write the Docs Before the API

Slide 1

Slide 1 text

Ben Ahmady - Write the Docs Prague 2019 @superdevx (Twitter) ben-superdevx (GitHub) Write the Docs Before the API

Slide 2

Slide 2 text

Our Vision We’re creating an open world where identity is the key to access

Slide 3

Slide 3 text

This talk ● Onﬁdo’s Developer Experience (intro) ● Our new API (v3) ● Docs-ﬁrst approach ● Feedback ● Positive outcomes and lessons learned ● Bonus: “Involving tech writers from the start?”

Slide 4

Slide 4 text

Onﬁdo Developer Experience

Slide 5

Slide 5 text

Onﬁdo’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)

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

The project: API v3

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

v2 pain points Product Support and Sales Engineers API logs Support tickets

Slide 10

Slide 10 text

Make things simpler ● Endpoint structure ● Request bodies ● Change default behaviour to what users expect ● Simplify the documentation itself

Slide 11

Slide 11 text

Docs-ﬁrst approach

Slide 12

Slide 12 text

Docs-ﬁrst 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.”

Slide 13

Slide 13 text

Docs-ﬁrst approach First-time, new experiment at Onﬁdo (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

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

Docs-ﬁrst approach (API v3 micro-team) ● Weekly meetings to discuss changes ● Establish docs instance workﬂow ● Open docs up for feedback (in “time windows”) ● Make changes to the API itself after feedback windows close

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Workﬂow 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

Slide 20

Slide 20 text

Before and after

Slide 21

Slide 21 text

Feedback

Slide 22

Slide 22 text

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”

Slide 23

Slide 23 text

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 ﬁxes to make to improve testing

Slide 24

Slide 24 text

Conclusions

Slide 25

Slide 25 text

Positive outcomes (pt 1) ● Success: https://documentation.onﬁdo.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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Next steps ● API v3 full release imminent ● Total Developer Hub design makeover ● GitLab “Visual Reviews” ● Lots more user research and iterations

Slide 29

Slide 29 text

Involve tech writers from the start…? Y/N

Slide 30

Slide 30 text

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!

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Involving tech writers from the start…? Disadvantages ● Projects change - sometimes dramatically ● Scepticism about value of dedicated docs writers ● Differing expectations ● Access to developers

Slide 33

Slide 33 text

Involving tech writers from the start All depends on project (and people) In our case, very successful: ● Strong, positive review culture ● Agile (Scrum) workﬂow ● Investment in project

Slide 34

Slide 34 text

Personal development bonuses For tech writers on the techy side: ● OpenAPI ● Testing in different languages (Java, PHP) ● GitLab CI

Slide 35

Slide 35 text

@superdevx (Twitter) ben-superdevx (GitHub) Thank you!