API/Dev docs style guide(s)?


I know we’ve talked about style guides on other threads, but I’m in need of something more specific, namely a style guide/guides that specifically address API reference docs (ideally) or at least developer-facing docs more generally.

I’ve got my own list of recommendations, but I sure could use something that might be viewed as more authoritative, or at the very least representative of common usage.

thanks to anyone who can help –




I will gladly share the style guide I am using here, keeping in mind it is 3-4 versions out of date and I’ve stripped out any sensitive information: Style Guide

I actually recently made a huge upgrade to our developer portal - the entire site is now generated from a few dozen RAML files using a RAML to markdown converter I spent 2 weeks writing in node.js (I was a web developer for 2 years).

Now instead of taking 30 minutes every time a new parameter is added to a resource, it takes 30 seconds to update!

Anyway, I was just a little excited because I saw this post and was excited to see someone else working on API documentation :smile:

  • Melissa


Melissa! Thank you!

Another question for you: do you generate new doc from the RAML spec whenever there is a change?

(I ask because we are converting Swagger to Asciidoc, but we currently are undecided about where changes to descriptions go. Some on the team want to update the description field in the YAML, and some want changes to go only into the Asciidoc. Would love to hear your thoughts!


We are in the process of hooking up the generator to a build process (TeamCity) to generate the docs automatically, but right now it’s all manual - make a change, run generator.

I’ve actually never heard of Asciidoc! I did research blueprint/swagger/RAML before we chose RAML, but Asciidoc never came up.

One thing I had to keep an eye out for, the description field in RAML for schema (resources) is limited to fitting in a single string, but the description field for requests can be rich text. That ended up being a pain for me, as we wanted markdown in the descriptions.


Asciidoc = big improvement over markdown. Sorry if I wasn’t clear – it’s not a REST API spec.

I also wasn’t clear enough in my question – if you need to update a description (for the API, for a parameter, for a method), do you edit the RAML? Or the markdown? Re-reading your first reply, I guess it must be the RAML, but we are talking about editing the markup (asciidoc instead of markdown in our case). Make sense?


Ahhh okay.

Yes, we update RAML to update descriptions, never the markdown.

The markdown is only used so the jekyll plugin we are using can transform it into the full developer website, using the awesome plugin Jekyll Doc Theme for Designers