Documentation Pages

[XVincentX]

• Adds Example generation strategy document
• Moves stuff out from the main Readme into separate docs pages
• Specify a little bit more what's going on with Validation response generation

[XVincentX]

Great catches @philsturgeon — I've pushed some changes and I'll move forward to responses docs

[philsturgeon]

This looks awesome so far!

Could we maybe move the CLI stuff from the main README into a new CLI docs file?

I know we have README in packages/cli/ etc but they are instructions for contributors who are looking, we should move end user docs to this top level docs folder so they're all displayed on our new hosted docs.

@marbemac had a really cool idea he started on for Spectral, which is to have ## Examples and then bullet point lists of common things we think users might want to do.

• Get Prism to show different named examples
• Create dynamic examples
• Show validation errors for garbage requests

That sort of thing. We highlight cool stuff and link directly to the docs/foo.md and the proper #header-id so folks can read about it, without making the README huge.

[XVincentX]

had a really cool idea he started on for Spectral, which is to have ## Examples and then bullet point lists of common things we think users might want to do.

It seems to me kind of a table of content of the docs directory, right?

[philsturgeon]

@XVincentX not so much table of contents, it's just some examples. Much like we have them in the readme at the moment, this is a link to somewhere else. Our documentation section will take care of standard navigation stuff like a ToC.