[handrews]

Yeah this article is more about how we (the OpenAPI Initiative) are designing the next versions of the OpenAPI Specification than it is about how to use it. The diagram does include both an OAD generator and editor, intended to encompass both code-first and description-first (which doesn't make too much difference for this blog post). The Moonwalk article is definitely more general purpose! This is "OK Moonwalk has a great vision, but how do we actually make it a real spec?" I've been using variations of this diagram in the weekly Moonwalk calls for the past month or two.

[throwaway2016a]

> OK Moonwalk has a great vision, but how do we actually make it a real spec?

I'm not sure the article really succeeds if that was the goal. I suspect that there might be some aspects of the discussion that are taking place that are missing from the article making it a little difficult for someone who wasn't in those discussions to connect the dots.

Don't get me wrong, I think the article had some useful pieces in it, I just think if that was the goal of the article it could possibly use some additional framing for people who don't have the full context.

With that said, I really appreciate transparency into the thought process!

[handrews]

> I just think if that was the goal of the article it could possibly use some additional framing for people who don't have the full context.

It's always a struggle to figure out how much explanation to put in before people see something like "20 minute read" and just refuse to read it. (BTW I don't mind the critical feedback at all- I'm just glad you found something useful in it).

But keep in mind that _we_ haven't answered "how do we actually make it a real spec?" either! This is a snapshot of our efforts at this particular moment. Also, there's a reason that this is "part one in a series" :-)