Introduction

What I'll talk about

• What makes dev doc unique
• Dev doc design patterns
• Docs-as-code characteristics
• Markdown and version control
• REST APIs and OpenAPI spec
• The jungle of publishing tools
• Lessons learned

Where to find more information

"API docs" versus "developer" docs

• All API docs are developer docs, but not vice versa
• API docs include both reference and non-reference content
• Tool options in this space are mind-boggling
• There's a tools gap for integrating API reference docs and
  non-reference content

Why not just use traditional HATs?

• Developers are authors
• API structure/templates
• API requests demo'd on page
• API docs are the product interface

Survey of API doc sites

• Let's begin descriptively
• Pick 3 from 100 API doc sites
• Identify common characteristics

Design patterns with API doc sites

• Structure and templates
• Website platform
• Abundant code samples
• Lengthy pages
• API Interactivity

Developers treat docs as code

• Markdown or rST
• Static site generators
• IDE-like text editor
• Git to manage content
• Build from server

Markdown is preferred syntax

• Readable as code
• Compatible with version control
• Semantics defined in YAML frontmatter
• Scripting languages handle complex scenarios
• Risk: Lack of standards creates tool lock-in

Git for managing content

• Ingenious way to collaborate
• Helps you understand engineering workflows
• More of a learning curve than your SSG
• The Git model scales

Build from server

• "Continuous delivery" is the killer feature
• No manual uploading/deploying files
• Focus on content

API reference content

• Use templates for common API sections
• Describe with OpenAPI specification
• Render with Swagger UI or other
• Integrate with non-reference docs

Authoring and publishing tools

4 categories of tools

1. Static site generators
2. Hosting and deployment options
3. Headless content management systems
4. Tools to render OpenAPI spec

1. Static site generators

• Jekyll
• Hugo
• Sphinx
• +350 more

Speed • Format • Community

2. Hosting and deployment options

• GitHub Pages
• CloudCannon
• Read the Docs
• Netlify
• Aerobatic

Continuous delivery • Integration

3. Headless CMSs

• Forestry.io
• Netlify CMS
• Readme.io
• + dozens more

Continuous delivery • Integration • Authentication

4. Tools to render OpenAPI spec

• Swagger UI (Demo)
• SwaggerHub (Demo)
• Readme.io (Demo)
• Spectacle (Demo)
• Stoplight.io(Demo)
• APIMATIC.io (Demo)
• Restlet Studio (Demo)

API Explorer • Client SDK generation • Versioning • Collaboration

Integration challenges

Need to combine API reference docs with
non-reference content

Which tool to choose for API docs?

1. Define your requirements
2. Choose your priorities
3. Consider the time you want to spend on tools
4. Hope that you don't sink months into the wrong tools and platforms

Lessons learned

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
• Embed Swagger UI directly onto page or link to it

View sample

My experience switching to docs-as-code

• Mostly love it, would never go back
• Continuous deployment with Git is the killer feature
• Love the control and flexibility of open source SSG
• Takes way more time than you think
• No good solution for search or translation

Other implementation realizations

• 3rd-party hosting ideal but company permission can be an issue
• Engineers understand infrastructure but not SSGs
• Collaborative effort with engineers, not a DIY project
• 1-2 repos max, feeding into same publishing pipeline

Confusing landscape, but here's what I know

• Describe REST with OpenAPI spec
• Build continously from the server
• Manage content with Git
• Seek 3rd-party solutions when possible
• Don't spend infinity in the rabbit hole of tools
• Weigh the tradeoff between control/flexibility versus time/effort/responsibility