
Ask HN: What's your preferred layout for API documentation? - rsto
I&#x27;m writing documentation for a public (REST) API and wonder which layout is preferred by developers.<p>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]).<p>In contrast, Mailgun uses two columns: a navigation pane and a colum including the API description and examples (see [2]).<p>Both layouts seem popular, and I&#x27;d like to better understand what&#x27;s making you prefer one over the other. I&#x27;m talking about reference documentation, assuming there&#x27;s also a separate user guide.<p>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&#x27;s probably just me?<p>Thanks for your thoughts!<p>[1] https:&#x2F;&#x2F;stripe.com&#x2F;docs&#x2F;api<p>[2] https:&#x2F;&#x2F;documentation.mailgun.com&#x2F;en&#x2F;latest&#x2F;api-sending.html<p>[3] https:&#x2F;&#x2F;github.com&#x2F;lord&#x2F;slate<p>(edit: simplified the layout descriptions)
======
dmlittle
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.

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

[https://libtmux.git-pull.com/en/latest/api.html](https://libtmux.git-
pull.com/en/latest/api.html)

[https://libvcs.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](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/](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](https://stripe.com/docs/api)

In addition, Heroku's platform API documentation is nice:
[https://devcenter.heroku.com/articles/platform-api-
reference](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](http://backbonejs.org/docs/backbone.html)

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

------
micael_dias
(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.

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

