1 of 31

When documenting is designing: How to assist API design as a technical writer

​

Write the Docs Prague 2021

Fabrizio Ferri Benedetti

2 of 31

About me

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

2

King�

Ohpen

New Relic�

Ohpen

Splunk�

<< Dark ages

Tech writer

API Writer

Product writer

Tech writer

Tech writer

3 of 31

Core assumption

(Tech) writers can improve anything built with words.

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

3

4 of 31

Pretty much anything

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

4

UI Text

Tech docs

Metadata

Code

Copy

Spells and charms

5 of 31

Words happen everywhere

​

​

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

5

Backend

APIs

UIs

Workflows

Code comments

API docs

Embedded docs

User docs

6 of 31

Words also happen to be design

​

​

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

6

APIs

UIs

API design

UX writing

7 of 31

What’s with APIs?

8 of 31

API designs are made of words

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

8

9 of 31

Because APIs enable conversations

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

9

REST API

GET /resource

Response

Stuff you don’t need to be concerned about

Client

Data

10 of 31

So, what is API Design?

API design refers to the process of developing application programming interfaces (APIs) that expose data and application functionality for use by developers and users.

​

-Red Hat

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

10

11 of 31

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

11

POST /dance

200 OK

API design is about choosing the right words to enable systems to converse

Help the robbies talk!

12 of 31

API design depends on how you build APIs

API First

  • Start with the design
  • Get feedback before coding (mock APIs, contract)
  • Code follows the design
  • Docs are first-class citizens

Code First

  • Start with code
  • No feedback on design till the developers work on it
  • Design describes the code
  • Documentation comes later

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

12

13 of 31

The problem with code first APIs

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

13

Pieter Bruegel the Elder - The Tower of Babel

14 of 31

API First workflow

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

14

User story

Refinement

Draft API design

Initial docs

Mock API

Publish specs

Incorporate feedback

Implement and verify

15 of 31

API description formats enable API First

  • Structured, easy-to-parse plain text (JSON/YAML)
  • Facilitate sharing
  • Single source of truth
  • Standardized

​

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

15

16 of 31

API Design is nobody’s a shared responsibility

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

16

API PM/PO

API Technical Writer

API Developers

QA Engineers

Engineering Manager

API Architect

API Designer?

17 of 31

The API designer <> Technical writer overlap

API Designer

  • Their primary tool is words
  • They use API description formats for designing APIs
  • They document as they design
  • They need that the API design is well documented
  • They are user advocates

​

​

Technical writer

  • Their primary tool is words
  • They use API description formats for documenting APIs
  • They design as they document
  • They need that the API design makes sense
  • They are user advocates

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

17

18 of 31

Why tech writers should bother

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

18

Documenting a bad API takes more time and generates less satisfaction

19 of 31

”Let’s document error responses...”

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

19

From “RESTful API Design: 13 Best Practices to Make Your Users Happy” (Florimond Manca, 2018)

20 of 31

Start with this simple question

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

20

©2021 NBCUniversal Media, LLC

21 of 31

1. Advocate for API First

  • Pitch API First design internally
  • Find allies in engineering and product management
  • Draft API First workflows and procedures based on your tech stack, then pitch them or ask for feedback
  • You can still do API First AND generate API specs from the code (so you can compare design and implementation)
  • Make sure versioning applies to the design, too

​

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

21

22 of 31

2. Push for API Design Guidelines

    • Guidelines make things more likely to happen
    • Make it collaborative; gather feedback, be open to changes
    • Create an API Design template based on the guidelines
      1. Start from user stories
      2. Identify actors and goals
      3. Identify and name resources
      4. Describe the data models and their relations
      5. Create the paths
      6. Turn all that into an API specification file

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

22

23 of 31

3. Create an API Style Guide for Docs

  • Design and docs guidelines partially overlap
  • How should contributors write descriptions?
  • What’s the terminology of your API/platform?

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

23

24 of 31

4. Own summaries and descriptions

  • Documentation entities in API specification formats are technical writing strongholds—own them!
  • Embed yourself in the design process so that you can be the editor all documentation fields (reference docs)
  • Make it easy for stakeholders to request reviews

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

24

25 of 31

5. Provide naming expertise

  • Naming is a key aspect of API design
  • Start by suggesting alternatives/raising concerns
  • Naming issues can be a symptom of something bigger
  • Set up office hours, create a Jira project, etc.

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

25

26 of 31

6. Join or set up API design reviews

  • API design reviews are for approving design decisions
  • Getting people in the same room/chat is key
  • Keep rules simple; always set an agenda
  • Offer to moderate the meetings

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

26

27 of 31

7. Fight for meaningful error messages

  • API consumers see tons of errors every day
  • Error codes should make sense (semantically)
  • Error messages should be clear and useful
  • Tech writers are often the first API consumers

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

27

28 of 31

7. Build an internal API Viewer

  • Internal API viewers are the town squares of API design
  • Build a simple solution to load in progress API specs
  • It can be a prelude to the client-facing dev portal

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

28

29 of 31

Ingredients for a simple API viewer

  1. API specs hosted in Postman
  2. React starter project
  3. Functions to call the Postman API
  4. Simple UI to select APIs and versions
  5. Some glue code to tie it all together
  6. ReDoc or Swagger as a component to render the API docs

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

29

30 of 31

Resources

  • The Design of Web APIs (2019)
  • APIs You Won’t Hate (Slack+Web)

​

​

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

30

31 of 31

POST /thanks�GET /talks/{talkId}/questions

418 I’m a Teapot

​

https://passo.uno

When documenting is designing: How to assist API design as a technical writer :: Write the Docs Prague 2021

31