Shuffle Ball Change

Sashay your way to clearer API documentation

Write the Docs | Portland 2021

Rachael Miller Stavchansky          

slides.com/rstav

A little background

Current role

Documentation Team Manager, Netlify

 

First role

The chorus of Katz!

 

What you'll learn

  • Benefits of working with API docs
  • How to start providing value
  • Methods for collaborating
  • How to draft clear guidelines
  • What any of this has to do
    with tap dancing

Benefits of working with API docs

  • Skills are in-demand

  • Helps enterprise users

  • Deepens product understanding

  • It's satisfying

Providing value to your organization

Dunning Kruger

effect

Imposter

syndrome

Providing value to your organization

Your
Audacious

Self

which brings us to tap dancing

Some context

Our focus today

API reference documentation

Processes, not tools

Case studies

How you do the things you do

Case study 1

Bulk edits

Initial Context

  • Microservices with inconsistent docs
  • Engineering org with outside consultants

Case study 1

Preparation

  • Researched REST APIs
  • Prioritized and scoped
  • Identified a primary contact
  • Audited the existing docs

 

Case study 1

Case study 1

Content development

  • Created a spreadsheet:
  • Content review
  • Bulk edits to source files
  • Current state for each endpoint summary, description, resource description
  • Clarified with primary contact
  • Added a suggested state for each item

Case study 1

Maintenance

  • Handed off to embedded writer
  • Added more consistency to other parts of the reference
  • Stayed involved as reviewer
  • Prioritized other external microservices

single story

map

of the API

spreadsheets aren't all bad

Case study 1

Takeaways

Case study 2

Writer owns the spec

Case study 2

Ownership

  • Context: relationship between REST OpenAPI spec and the code base
  • Tight ownership by tech writer
  • Support from developers

Case study 2

Development & QA process

  • Keep up with pace of development
  • Writer tests and verifies
  • Support from QA

satisfying, if you can keep up

communication is key

deeply engaged

Case study 2

Takeaways

Case study 3

Chasing commits

Case study 3

Ownership

  • Context: preview stage GraphQL API
  • Developers create first draft
  • Code comments in source code
  • Tech writer as editor

Development

  • Fast-paced environment
  • Monitor commits for new content

developer-driven

chasing was stressful

lightweight involvement

Case study 3

Takeaways

Case study 4

API guidelines

Case study 4

Initial context

Case study 4

Why guidelines?

  • Amplify writers' work
  • Opinionated, in a good way
  • Standardized if enforced

Case study 4

Building guidelines

  • Identify elements

  • Draft guideline for each

Case study 4

Building guidelines

Case study 4

Building guidelines

Case study 4

Building guidelines

  • Identify elements

  • Draft guideline for each

  • Compare against others

  • Iterate

  • Get feedback

  • Document with clear examples

Case study 4

Example guidelines

 

Case study 4

Example guidelines

 

module Api
  module V1
    # @resource Accounts
    # @tag_group User Accounts
    # Endpoints for managing accounts.
    class AccountsController < ApiController
    ...

    # Returns a list of accounts for a user.
    #
    # @summary Return accounts 
    # @path [GET] /api/v1/accounts
    # @response [Account] 200
    def index
    ...
    end

Case study 4

Example

guidelines

 

Case study 4

Building guidelines

  • Identify elements

  • Draft guideline for each

  • Compare against others

  • Iterate

  • Get feedback

  • Document with clear examples

  • Socialize

  • Encourage & enforce

Case study 4

Building guidelines

Case study 4

Outcome

 

Case study 4

Outcome

 

Case study 4

Outcome

 

developer & docs partnership

less control

less need to verify

Case study 4

Takeaways

 

Looking back  

  • Ownership & processes can be very different
  • Variables to consider:
    • Resources
    • Organizational priorities
    • Company culture
  • Ask about ownership & process when interviewing
  • Tap into your audacious self

 

Thank you!

Shuffle Ball Change: Sashay your way to clearer API documentation

By Rachael Stavchansky

Made with Slides.com

Shuffle Ball Change: Sashay your way to clearer API documentation

Learn how to tap into your audacious self to improve API documentation at your organization. In this talk, I’ll compare processes across a few different companies and teams for authoring, editing, and maintaining various types of API reference documentation.

  • 1,070

More from Rachael Stavchansky