Make our documentation the best in the world

[rmccue]

WP API's documentation should be first-class, and better than every other API out there. This might seem unachievable, but let's aim for it anyway. :stars:

The documentation itself currently lives in the main WP-API repo, but we can move it here if that works better.

How do we do this? Here's some initial things I can see that we need to do:

• [ ] Include guides on the site
• [ ] Include OAuth documentation on the site
• [ ] Integrate all route documentation

This is a tracking ticket for everything else, let's talk about how to do this here, and handle specifics in individual tickets.

Stripe's API docs are widely considered some of the best, let's take inspiration from them where possible. Parse also has some great thoughts.

[rmccue]

With route documentation, should we use the URLs themselves instead? What's the best way to format our sidebar navigation?

Example from WooCommerce's docs:

Counter-example from Stripe's docs:

What ours looks like currently:

[pollyplummer]

A few thoughts in response:

On how to structure the sidebar:

In the current theme, side navigation anchor links seem to be broken. It lists each endpoint with "input" and "response" subnav items, but this becomes a bit repetitive and unwieldly. I like how the Stripe API docs sidebar navigation lists the main object with very readable subnav items for each endpoint, describing what you can do them, ie. Charges > Create a Charge.

In the same way, I'd suggest restructuring our nav to be like so:

Posts

• Create a post
• Retrieve a post
• etc

Media

• Create Attachment
• Get Attachment

(Recommend removing "Input" and "response" subnav items entirely.)

Docs Need a Better Theme

I find the current Flatdoc theme very difficult to read, due to small text and very little contrast. It's all grey and very light aqua and strains the eyes. I would suggest using a different documentation theme. One that looks interesting is MkDocs, which you can host on Github pages or on a site of its own. It was built for writing docs in Markdown and includes a built-in devserver allowing you to preview your documentation as you're writing it. MkDocs also has a number of different themes available that you can apply, including ReadTheDocs, which provides much higher contrast.

Another option would be to install WordPress on wp-api.github.io and use or create a WordPress documentation theme.

The better the docs are, the faster developers will be able to start building with the API. I think it would be good to add a section linking to some examples of projects that utilize the WP API as some people learn better from looking at the code of real-world examples.

[bradoyler]

Are there any docs on how to use the filter querystring? ie. /posts?filter[type]=person

[amr]

I think you guys might want to check asciidoctor.org, it might be a better companion than MD in assisting you in writing great technical docs. With MD, I always stopped writing and went on how to present the information at hand using its limited formatting features. Great for comments and general writings, but not fit for technical writing, IMHO.