Key points in this video

Tools are specialized software for achieving a specific task (such as editing or publishing)

The tools are not the workflow; they’re merely implementation details.

Some kinds of tools we can use for documentation:

• General-purpose writing tools
• Wikis
• Third-party SaaS
• Open-source libraries
• Custom tools

When picking a tool,

• Pick a tool that suits your chosen approach and your situation
• Combine multiple tools if you need to, but be careful of fragmentation
• You can build your own tool, but don’t get distracted!
• Remember, good API documentation is not about choosing the right tool. Here's ALgolia's story.

Helpful Links

Third party documentation services:

• Readme
• Apiary
• Postman
• Stoplight
• Apimatic

Open-source documentation libraries:

• Static site generators: see staticgen.com
• OpenAPI spec to docs site: Redoc, Spectacle, SwaggerUI
• SaaS that complements open-source offering: Redocly, SwaggerHub
• apidoc
• Scribe (Laravel, Node.js)

Our case study (Venus)

Approach 1

• Docs-as-code
• Custom tool to extract all endpoints from the codebase, combine with info from existing OpenAPI files into new OpenAPI spec
• Redoc/Spectacle to convert OpenAPI spec to UI

Advantages

• Can leverage existing OpenAPI spec
• Mostly automated
• Docs close to code

Disadvantages

• Would take time to build and maintain
• Doesn’t allow for separate conceptual docs

Approach 2

• Postman collections + Postman documentation

Advantages:

• Easy setup
• Can integrate with dev workflow and “self-document”
• Easy to test and update

Disadvantages:

• Would need to grant manual access to everyone who needs it
• Would take a long time to get all docs complete
• Relies somewhat on human interaction
• Doesn’t allow for separate conceptual docs
• Doesn’t live close to the code, so not very discoverable

Exercise

Remember Hazam (from the lesson on requirements)? Based on what you’ve learnt so far, what tools and approaches would you pick for documenting the Hazam API? You can come up with multiple options, and the advantages and disadvantages of each.

You can assume that Hazam is written in a language and framework you’re familiar with (such as Ruby/Rails, PHP/Laravel).