📖 De-monolith the README

[martincostello]

The README for this repository is currently...pretty chonky.

With large changes coming to Swasbuckle.AspNetCore coming later this year to support OpenAPI 3.1 (see ##2349), now is a good time to restructure the documentation and move the majority of the content out of README.md.

The initial proposed solution here is to create a docs folder, and move the majority of the content into dedicated markdown files there, which we can link to from a docs/README.md index file.

Then the README in the root can cover the essentials (installing, building, the elevator pitch, etc) with the low-level specifics in dedicated content linked to via the docs index from there.

This also presents an opportunity to review the content and ensure it's up to date for v8.

This will then unlock the ability to (more easily) write a v8 ➡ vNext migration guide to deal with the breaking changes for OpenAPI 3.1 without making the README even bigger than it is today.

With that new structure in place, as a stretch goal, we could copy the model used in App-vNext/Polly and set up a docfx site that is deployed to GitHub Pages with compile-checked documentation we can maintain.

Community participation in this endeavour is welcome!

[martincostello]

/cc @peter-csala just in case this is something I could tempt you with helping out with as you're so great with documentation 😃

[peter-csala]

@martincostello I will have some free capacity in May. Please ping me then.

[martincostello]

in May. Please ping me then.

ping 😉

[peter-csala]

in May. Please ping me then.

ping 😉

I can start working on this on the 12th of May week. Will you setup docfx till then?

[martincostello]

docfx is just a stretch goal for after the docs are improved, as essentially we just have one giant document right now. It also requires repo setup that I cannot do myself, even if we had the code ready to go.

The main goal here is to break up the documentation and move it out of the README and into dedicated files in /docs, and the iterate from there.

[peter-csala]

I think we can do this in three separate PRs:

1. Slice the content of the current README.md and place them under the /docs (Do not alter the content)
2. Improve the formatting of the contents (like use GitHub's tip and note notations)
3. Shrink the main README.md by pointing to the new docs

@martincostello What do you think?

[martincostello]

Yep, that sounds good. It's pretty much what I was thinking.

We'd want to keep a high-level "elevator pitch" and minimal "getting started" content in the actual README, but most of the content can move as it's documentation for lots of specific use cases.

[peter-csala]

@martincostello Please assign this ticket to me.