Common Approaches and Tools Part 2

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:

Open-source documentation libraries:

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).


Complete and Continue  
Discussion

0 comments