In short, we wanted an API spec that was much more readable and efficient, showed the structure of the API more clearly, and promoted consistency and reuse. We wanted an API spec that was intuitive enough to just type out in an editor when designing an API. And we iterated on it quite a bit in real-world cases to be really convinced it was worth introducing this different approach.
couldn't agree more that it ain't much without tooling -- RAML's been out for only about 24 hours, but open-source tooling is right around the corner (weeks, not months).
(disclaimer, I'm from the RAML workgroup -- nice to see you here, Jakub!)
As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.
We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.
We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.
I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.
I like to think design-first and if possible in the most minimal fashion that captures the interface, but I certainly see (and share) the appeal of writing working code. In many cases like that (including APIs that are already implemented in code), generating a clean RAML spec from the code is a good way of capturing the interface itself, in a very readable way that shows the structure. Thanks for these links -- very interesting!