Define the JSON Schema Documentation Strategy

[benjagm]

Problem: Documentation is not as good as it could be.

🚨This Issue and Roadmap Item is marked as "deferred", meaning it is low priority and should not be a focus over other items in the roadmap. However, we should identify opportunities to empower others to contribute to this task, if helpful.

@benjagm to define define success criteria, deliverables, and breakdown of tasks.

Assessed as high impact/medium effort during our collaborators summit 2023.

⚠️ Note on the scope of this issue

The scope of this issue includes only defining the strategy, not the execution. The execution of this Strategy is being managed in the issue #158

Purpose

The purpose of this issue is to implement the JSON Schema docs vision proposed in this discussion #386 . 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.

Repository

All the changes will be implemented in the new website repo: https://github.com/json-schema-org/website

New Content Architecture

For this new content architecture we are adopting the diataxis documentation principles. See below the proposal:

• Overview

  • What is JSON Schema
  • Use Cases
  • Roadmap
  • Vision
  • Release and Versioning
  • Support and Community
  • Sponsors
  • FAQ

• Getting Started

  • Getting started
  • Creating a schema
  • Examples
    • Miscellaneous examples
    • Modelling a file system
    • Other examples

• Guides:

• Reference:

  • JSON Schema Glossary
  • Link to Learn JSON Schema
  • Understanding JSON Schema
  • For implementers

• Specification

  • Overview (New)

Plan

Please access the details plan in the issue #158 using this direct link: #158 (comment)

Success Metrics

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

• Deliver at least to Release 6 in 2023-24
• The feedback received from the community regarding the documentation.
• The number of issues resolved in the documentation project.
• +15% YoY number of pages views.
• -10% YoY pages bounce rate.
• Decrease in the number of technical questions
• The number of docs contributors.

Risks

The risks associated with the documentation project includes:

• 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

We'll use milestones to group releases.