Publishing API documentation

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

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

• GitHub Pages
• CloudCannon
• Netlify
• Aerobatic

3. Tools to render OpenAPI spec

• Swagger UI (Demo)
• SwaggerHub (Demo)
• Readme.com (Demo)
• DeveloperHub.io (Demo)
• Redoc (Demo)
• Spectacle (Demo)
• Stoplight Studio (Demo)
• APIMATIC.io (Demo)
• Apiary (Demo)

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?