CADL as approached by a newbie

[AdamGlass]

Goal: get in newbie mindset, provide feedback on github content.

• Github lacks an about section so i have to scroll down to find out what it is
• not sure why there are no releases and packages listed on right hand side in github
• Nothing in README says Microsoft uses this for production SDKs, or really does anything else with this. Could be a research project fro description. Might as well say something about how we use it.
• is it exiting preview?
• Seems like it could use a second level of descrption of ok, using this language you do X and it can generate openapi thingies, and do some other stuff.
• There is this list of packages that dominates over the getting started. I honestly don't now why or even why there are packages yet. I haven't gotten to the thing where i find out this is some NPM/Node.js thing.
• Drops pretty quickly into getting started, really hasn't communicated what the value is yet. Tell me more before you get to the icky stuf.
• Only node 16 LTS? Is it that or Later?
• Install step 3 is first reference to OpenApi
• Why not cover tutorial, languag spec earlier?
• Isn't installing language extensions 'optional'?
• Step 7 is first time tutorial mentioned. We really communicated value yet. maybe show an example earlier? or describe some scenario?
• Is it normal to put usage after install? couldn't you put install on a seperate page, get to usage faster and maybe communicate value.
• some previous line implies i have to do 'npm cadl'. later lines just use 'cadl'.
• Compiling cadl "source" to openapi3 specification. is "source" the right word here 'CADL file' or CADL description or something?
• Installing edit extensions are referred to again here. maybe just do as an optional in the install section?

Overall comment on documentation. Tutorial link is buried. Never gives a link to the language specification. Seems like you'd want to explain value, Point them to the tutorial and then the language specification.. then maybe links to the other supplementary docs. The language specification is present if you go digging in the docs directory.

adamg@microsoft.com

[bterlson]

This is awesome, thank you!

[markcowl]

@AdamGlass Thanks for all the feedback, this is terrific! If you have worked on a project long enough, it is easy to lose the 'getting started' perspective.

[mikekistler]

Here's a concrete set of changes I think we should make that will address much of @AdamGlass 's feedback:

• Add one or two sentence “About” to the repo.
• Modify publishing process to create a GitHub “release” for each npm publish
• Move the Packages section to the end of the Readme
• Add “Prerequisites” section at the top of “Getting Started”. Requires Node 16 or later.
• Add a paragraph to the Intro section to give a high-level description of the OpenAPI use case. This must communicate value and motivate readers to continue.
• Link to the Tutorial and Playground from the intro section
• Use “npx cadl” consistently as the way to run the cadl compiler.
• Remove step 5 from Getting Started (Install editor extension) as it is covered later.

[AdamGlass]

Based on when i mentioned this to some other folks who had an existing to OpenAPI generator story -- you may want to motivate this further. Basically what do i get out of this that I don't get out of a 'take a native struct' and generate an openapi description for it. Maybe your argument is that this CADL description is another 2 steps removed from a specific implementation and thus better -- in any case make your argument.