Proposal for defining a Vision for the JSON Schema Docs

[benjagm]

Context

The JSON Schema history started back in 2007. Since then, different leadership teams have focused on evolving the specification, resulting in multiple specification releases. Unfortunately, during all this time, docs have never been a priority, resulting in JSON Schema documentation needing more consistency and structure, and making it difficult for new users to understand and implement JSON Schema.

Our current docs are just a bucket of very heterogeneous resources added over time, including a book, different specification definitions, and some examples, all with totally different tone and format, and with every new spec release, the problem does nothing but grow.

Purpose

The purpose of this Community discussion is to define together a clear vision and direction for the documentation of the JSON Schema project. This project aims to improve the consistency, structure, scalability and accessibility of the JSON Schema documentation, to help new schema developers understand and implement JSON Schema more easily and to help JSON Schema implementers to navigate the complexity of defining new JSON Schema implementations.

Scope

The scope of this project includes:

• Creating a new documentation architecture that provides consistent, clear, and comprehensive documentation for JSON Schema that scales.
• Improve the existing guides an examples to provide a consistent and improved experience.
• Provide an alternative to "Understanding JSON Schema" because it is a book, and developer docs works differently.
• Define tutorials to help new implementers to define new implementations.
• Define tutorials to help implementers to use the test suite and Bowtie.
• Define overview docs such us: Roadmap, vision, release and versioning, support and FAQ.
• Revamp the JSON Schema glossary.
• Integrate Learn JSON Schema as official reference adding the examples.
• Review and refine the the specs docs to provide a consistent and integrated experience.
• Enable ways to capture feedback from the community.
• Provide internal guides to help with maintaining and extending the docs.

Objectives

The objectives of this project are:

• Develop a new documentation architecture that scales over time providing and provides consistent, clear, and comprehensive documentation for JSON Schema
• Provide comprehensive documentation that covers all aspects of JSON Schema for the identified personas: .
• Ensure that the documentation is accessible and understandable to both junior and experienced practitioners.
• Incorporate user feedback to continually improve the documentation and address the needs of the community.
• Provide a comprehensive plan to implement the project.
• Establish docs as a priority for the future of JSON Schema.

Plan

🏁 Release 0
Define the new content Structure. See issue #9 in website project.

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

🏁 Release 2
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)

🏁 Release 7
Integrate Learnjsonschema

🏁 Release 8
Tutorial for Bowtie
Tutorial for Test Suite

🏁 Release 9
Replace Understanding JSON Schema

🏁 Release 10
Tutorial creating and maintaining a JSON Schema Implementation

Metrics

The metrics for measuring the success of the documentation project include:

• The feedback received from the community regarding the documentation.
• The number of issues resolved in the documentation project.
• The number of docs pages views.
• The docs pages bounce rate.
• Decrease in the number of technical questions
• The number of docs contributors.

Risks

The risks associated with the documentation project include:

• Insufficient resources (tools, personnel, budget) to develop and maintain the documentation.
• Difficulties in developing the new documentation because of the deep knowledge required for it.
• User adoption of the new documentation.

Governance

Work in progress

Communication plan

TBD

Collaborating with the vision development

Please provide feedback in this plan and let us know what is missing and how to get it better.

[aku1310]

Hi, after going through the website repository, it appears that the sections on "What is JSON Schema" and "Creating a Schema" have already been completed. However, please correct me if I misunderstood.

Regarding the glossary, I do have some suggestions. One suggestion is to enhance the glossary entries by including practical examples or use cases for some of the complex terms (the ones that would be new to beginners). These real-world scenarios can help newcomers grasp the concepts more easily and understand how the terms are applied in practice. Additionally, organizing the content into sub-categories can provide better clarity and make it easier for readers to navigate through the glossary.

If the project's documentation is open to contributions, I would be delighted to participate! I can contribute by enhancing the content and helping with the UI too if needed. Please let me know how I can contribute, as I'm eager to assist in making the documentation more comprehensive and user-friendly

[benjagm]

Thanks a lot for your interest @aku1310 !! We are excited to get your support.

This discussion was created to capture feedback before past May's Team Summit but during the Summit improve the documentation appeared as a clear objective for 23-24 and was included in the roadmap. Having said that we can consider this proposal as an approved plan to start with.

In parallel, we are working in launching a new website (see repo) and all the work we have done is that repo instead of the repo of the current site this is why the Release 0 and 1 of this plan are completed but available only in the new website.

Moving forward I'd like to continue the collaboration using the issue #421 associated with 23-24 Roadmap and implement all the changes in the repo of the new site. I need to update issue today with all the context but my suggestion to star is:

1. Add all the details of the plan to #421 today.
2. Review the Release 1 to add some examples in What is JSON schema page before starting with Release 2.