RAML Experience - Help for Tutorial Improvements


#1

Hi guys,

IMHO, there are two different journeys of how you experience RAML (let’s call it RAMLX). The first journey is all about coming in with zero knowledge, wanting to learn all about the RAML spec and tools, and be forearmed for everything coming after a point where you create your own API. The second is really about how you experience RAML creating your first project using the tools and going live. The first part of the full journey I am calling the PreRAMLX and the second part, you might have a guess already, PostRAMLX.

I would like to execute a little survey about the PreRAMLX including the tutorials we have right now and IYHO what is missing. Please be very honest and tell us your experience in your journey to learn RAML. Are the tutorials enough? Is the use case good enough? Were all needed resources/information there to learn RAML? Is the provided documentation for the specification clear enough and contains all information?

Your answer on this can also include how you learned RAML and what information you used from different blogs or resources.

BTW, there will be a similar survey for PostRAMLX, but let’s concentrate first on the learning journey. This is the perfect chance for you to improve the way new people will experience their own journey with RAML. So please all, participate and help us.

Cheers,
Christian


#2

#3

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.


#4

Hi @justjacksonn - Thanks for your feedback. I’ll take some of it to the PreRAMLX survey and will move parts to the PostRAMLX which will come later. You’re far ahead my friend :wink:


#5

As someone who is new to RAML, I am finding it hard to understand what all the errors I receive mean.


#6

Agree, its something we would need to work on on the parser side. I’ll take that as an enhancement request. Thanks a lot!

@SCuvanov what parser do you use and also can you give some examples?


#7

Here is an example, this is a post I made earlier.