from Hacker News

Ask HN: What's your preferred layout for API documentation?

by rsto on 7/27/17, 6:12 PM with 5 comments

I'm writing documentation for a public (REST) API and wonder which layout is preferred by developers.

For example, Stripe uses a three-column layout: a navigation pane, a column to describe the API, a column with examples and error codes (see [1]).

In contrast, Mailgun uses two columns: a navigation pane and a colum including the API description and examples (see [2]).

Both layouts seem popular, and I'd like to better understand what's making you prefer one over the other. I'm talking about reference documentation, assuming there's also a separate user guide.

Personally, I find the three column layout harder to read: the example pane often wastes a lot of space and squeezes the actual documentation in the middle. On the other hand, I see more and more sites (and tools [3]) using that layout, so that's probably just me?

Thanks for your thoughts!

[1] https://stripe.com/docs/api

[2] https://documentation.mailgun.com/en/latest/api-sending.html

[3] https://github.com/lord/slate

(edit: simplified the layout descriptions)

  • by dmlittle on 7/29/17, 5:50 PM

    At the end of the day content accuracy is _a lot_ more important than content layout. There is nothing more frustrating than trying to follow the guidelines of an API Documentation and not being able to make the request you want.

    My suggestions would be the following: 1) Make sure the API docs are up to date! 2) For each API route, mention all possible fields as well as their type and maybe a short description of what they do if it's not obvious. 3) If you're providing wrappers, show an example of how to use them with each endpoint.

    If you make sure you're doing 1 & 2, your documentation will be helpful and easy to use. I work for an API company and we've made sure that our API is always up-to-date by automating it. If we ever add, remove or rename a certain parameter in a new API version, the documentation will reflect those changes as soon as they go live without us have to update the documentation manually. This has proven to be highly effective as it guarantees our docs are always right and up-to-date.

  • by git-pull on 7/27/17, 10:01 PM

    For python, here's what I use with sphinx-doc:

    https://libtmux.git-pull.com/en/latest/api.html

    https://libvcs.git-pull.com/en/latest/api.html

    That is, global + expanded local ToC Section Navigation on the left, and laying out the API docs like python code (parenthesis wrapping parameters).

    The tool that powers it is sphinx.ext.autodoc (http://www.sphinx-doc.org/en/stable/ext/autodoc.html). While it's opinionated toward Python, there are tools like Breathe (https://breathe.readthedocs.io/en/latest/) that can use doxygen's XML output to generate docs, too.

    For REST-based API's that can be widdled down to language-library abstractions, I concur with stripe API documentation: https://stripe.com/docs/api

    In addition, Heroku's platform API documentation is nice: https://devcenter.heroku.com/articles/platform-api-reference. Downside is the ToC makes the docs top-heavy.

    Other points:

    - I think it's OK to infer readers are going to be using Command/Ctrl-F searches liberally when viewing docs.

    - For javascript (to augment what's already there), I like annotated source if the library is small enough, e.g. http://backbonejs.org/docs/backbone.html

  • by twobyfour on 7/29/17, 4:33 PM

    Multiple pages for the docs instead of trying to fit everything on one page. Everything on one page (especially if you use more javascript than is strictly necessary to display the docs - as Stripe does) is slower and makes it harder to find and bookmark things.

    When reading docs, I prefer to have tons of tabs open to various sections than to be constantly scrolling back and forth between them.

    And yeah, please also avoid 3-column. It may be convenient on a 4K display in horizontal layout, but not all of us are viewing on that sort of monitor at all times. Stripe's docs are even more painful than usual when your viewport is ~1Kpx wide.

    Pretty much everything on readthedocs.org is laid out comfortably. That's my gold standard.

  • by micael_dias on 7/27/17, 6:14 PM

    (1) Not sure if it's fully the layout but no API documentation I came across was as easy as Stripe's for me to understand. Probably helps that they use "Entities" to describe the objects.

  • by rl3 on 7/28/17, 10:48 PM

    Maybe go with a two column layout and make the examples collapsed by default. Put an expansion toggle button in the header of the nav column, as well as the option for individual expansion.