Improve Docs and Spec navigation

[benjagm]

Draft content Structure

• Overview

  • What is JSON Schema (New)
  • Use Cases (New)
  • Roadmap (New optional)
  • Vision (New)
  • Release and Versioning (New)
  • Support and Community (New)
  • FAQ (This is new)

• Getting Started

  • Getting started old.
    Example
  • Creating a schema (Existing getting started, but needs lots of work)
  • Examples
    • Miscellaneous examples (Needs work)
    • Modelling a file system (Needs work)
    • Other examples (Needs work)

• Tutorials:

• Reference:

  • JSON Schema Glossary (Outdated)
  • Learn JSON Schema (Link to https://www.learnjsonschema.com)
  • Understanding JSON Schema (Existing - The structure of the book)

• Specification

  • Overview (New)
  • Specification (Existing but poorly structured with multiple embedded sections. Requires analysis and break it into pieces)

[benjagm]

Made some changes in the docs structure and prepared this proposal of tools prioritization:

Release 1
overview\What is JSON schema (New)
learn\Getting started (https://json-schema.org/learn/)

Release 2
learn\Creating a schema (https://json-schema.org/learn/getting-started-step-by-step.html)
Examples: Improve format and structure

Release 3
learn\Glossary (https://json-schema.org/learn/glossary.html)
overview\Roadmap
overview\Support and Community (New)

Release 4
Specification:
- Improve format and structure.
- Embed the old html format into the new format.

Release 5
overview\Use Cases (New)
overview\Vision (New)
overview\Release and Versioning (New)

[mjgutermuth]

I think this looks good. One small change I'd suggest is in the "Reference" section—I think this could be more broad than just that external link. I would suggest nesting the JSON Schema Glossary and Understanding JSON Schema in this section.

So it would look like this:

• Reference
  • JSON Schema Glossary
  • Learn JSON Schema
  • Understanding JSON Schema

I think this would make the navigation cleaner and keep the tutorial/how-to content easy to find.

I also think "Support and Community" could be its own top-level item, and FAQ could fall under that. I think it's okay either way, though.

[benjagm]

Thanks Melinda. I updated the taxonomy to reflect your feedback and I validated with the team both, the taxonomy and the releases so we have green light to start with Release 1.

[benjagm]

Completed until release 1. The works will continue in issue #158