I think what you have isn’t a bad start, but more detailed examples, more in depth about traits (and any soon to be 1.0 features that enhance RAML’s capabilities), security, contexts, etc would be a big improvement. I also think a RAML syntax/code completion plugin for the popular IDEs like Eclipse, IntelliJ, NetBeans, .Net and Sublime would really help. As was noted in some forum posts, large RAML files slow down rendering terribly in the current web editor. Having plugins with both syntax color (which exists for Sublime) and code completion (necessary to provide the same ease of modeling that your web editor provides), would help adoption quite a bit more I think. My biggest problem is having to copy/paste my files back and forth to your web editor to benefit from code completion. Sure, I could learn it or copy/paste an example then retrofit my own API in to it… but that isn’t nearly as useful as an actual IDE plugin that allows me to work in the IDE I use every day. As also mentioned, the web editor is just too slow for larger files. Even when I run my own modified version of the editor locally, it’s still not nearly as convenient as having it work in my IDE.
Various How Do I topics could be useful as well. They would offer quick jump points to specific questions (with answers) that could be community driven.
Much better explanation around relative and absolute paths would be helpful. I am not quite clear, for example, if I publish a RAML file to my site (with the modified editor), how to work with relative defined paths in the RAML file or if they need to be absolute.
A section on “things RAML can’t do yet” might be good to have… possibly with features that are planned and those that are not considered if there are any. I assume if HATEOAS can be managed in the 1.0 spec (via relations, etc?) there isn’t much RAML couldn’t do.
Maybe a bit more around “reuse” so as to avoid very large RAML files… such as working with multiple includes, reusable snippets, etc. I think Traits address some of this.
A good deal more info around XSD and JSON Schema. A lot of existing APIs will be built around XSDs, and while RAML supports it, it’s not clear (at least to me) other than just displaying the source XSD what else can be done with XSD. Is it purely just a display source in generated help? Along the same lines is how to utilize XSD and JSON Schema (side by side or otherwise) in code/generators to generate POJOs and such from XSD/JSON Schema. I’d even say put some info in there around migrating XSD to JSON Schema (the benefits of why to do it, etc) perhaps with even a tool on the site to allow some sort of conversion process to be tried. Also some differences between the two formats… sure we can look on the web, but having info/pointers right on your site would make it that much nicer to have at our fingertips.
It would be greatly appreciated if we had more regular updates as to what is going on with RAML (the spec, tooling, people using it, people contributing to it).
That’s about it for now.