How to Write Documentation for Kazoo!#

Consistency in documentation is a win for everyone, including your future self. Write the docs! We're here to help.

Rubric#

What we're looking for when evaluating documentation:

Top-level#

When writing top-level application docs, we're looking for:

  • Basics of API usage
  • Commonalities among all endpoints
  • ASCII Art of various Erlang process trees, FSM transitions, etc
  • SUP commands available

Per-endpoint#

When writing docs for API endpoints, we'd like to strive for:

  • Example request/response formats
  • As many as needed to demostrate usage
  • Keep it terse - no storytelling needed. Just the facts ma'am!
  • Suggested use cases (brief)
  • Bullet list of common ways to use the API
  • Links to user guides or tutorials of why to use this endpoint
  • Common pitfalls when using the endpoint
  • Conflicting settings to watch out for

Template Rules#

When creating a new markdown document, consider the following rules:

  1. Headings should only be h3 (###) or bigger, as h1 and h2 headers are used in the doc-generating code.

You can take a look at the index page and the error include from the slate repo for some of the syntax for creating code samples, tables, etc.

API Descriptions#

It would be great to have:

  • An About section briefly describing the endpoint
  • Descriptions of the relevant fields (defined in the schema for the resource)
  • Listing of URI segments available, with HTTP methods
  • Code sample for at least a cURL command; bonus points if you include PHP SDK equivalents.
  • Differences between versions of the endpoint, if any

Tools used#

Catologuing some of the tools used:

  • Multi-line search/replace of comment sections: find . -name "*.md" -print | xargs perl -i -pe 'BEGIN {undef $/;} s/\/\*\n.+?\*\///smg'

Edit this page here