Publishing API documentation

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/publishing_api_docs

Tool expertise is one value we add

27% use static site generators

59% follow a docs-as-code approach

45% use Markdown as source format

55% helped develop pub solution

73% manage content in Git

50% have continuous integration

Why not use traditional HATs?

Reasons to avoid traditional HATS

  • Developers often collaborate with docs
  • Developers are allergic to XML
  • Binary files don't version well in Git
  • API docs need custom structures for reference topics
  • Users want "Try it out" API explorers
  • Automatic syntax highlighting is a must
  • API docs are the product interface and must be attractive

The Docs-as-Code model

Characteristics of docs-as-code

  • Lightweight markup (e.g., Markdown)
  • Static site generators (e.g., Hugo)
  • IDE-like text editor (e.g., Atom)
  • Version control to manage content (e.g., Git)
  • Build from server (e.g., Continuous Integration)

Real-time demonstration

Demonstration of docs-as-code publishing...

JAMstack: JavaScript, APIs, Markup

JAMstack

Several categories of tools

  1. Static site generators
  2. Hosting and deployment options
  3. Tools to render OpenAPI spec

1. Static site generators

2. Hosting and deployment options

3. Tools to render OpenAPI spec

Integration challenges

Samples: Sendgrid, Spotify, Strava

Custom: My current setup at work

  • Jekyll + custom theme with no header/footer
  • Use existing internal Git infrastructure
  • Custom-built publishing pipeline
    • Builds output, then ingests HTML into S3
    • Server requests pull matching files from S3 store and inserts into template with header/footer

View samples

Activity 7a: Set up a GitHub wiki

Activity 7b: Clone your GitHub repo locally

Activity 7c: Push local changes to the remote

Questions?