In terms of API documentation, the biggest problem is making sure the documentation is in sync with the actual code. I'm looking into using JSON Schema [1] along with Swagger and Dredd [2]. Making it all language-agnostic is a key. If anyone is doing anything similar, please, share your experience.
We have hundreds of APIs, and we use RAML + json schema.
Since Swagger (OpenAPI) seems to be gaining ascendancy, I recently (some months ago) looked at migrating off of RAML, but at that time the Swagger guys had a philosophy that they would only support a subset of json schema.
I get their reasons - they want to be able to generate code. But the things they didn't support (like oneOf - needed whenever you have a set of resources of varying types) are a show stopper for many APIs with even moderately complex payloads.
For us at least, its more important to have a single source of truth for our APIs than to be able to generate code from the specs. Hence we remain on RAML (which seems great - just looking like its losing the popularity contest).
We also use RAML + json schema primarily as the single source of truth. We use https://jsonschema.net to generate json schema by providing it examples.
Ensuring documentation is in sync with code is straightforward if you have tooling in place to generate documentation from code. For example, at edX we use Django REST Framework and django-rest-swagger. Our Swagger docs are always up-to-date.
[1] http://json-schema.org/
[2] http://dredd.readthedocs.io/en/latest/