Google Season Of Docs 2023 Proposal for JSON Schema

[benjagm]

Update the documentation architecture of JSON Schema

About JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It defines how pieces of JSON should be structured, making it easy to ensure that they are formatted correctly, and it is useful for automated testing and validating. In addition, JSON Schema provides clear human- and machine-readable documentation.

JSON Schema has become the de facto way to define API requests and responses, establishing it as an essential ingredient in all API operations today.

About this project

🔎 The documentation problem of JSON Schema

JSON Schema is an open source specification whose history started back in 2007. Since then, different leadership teams have focused on evolving the specification, resulting in 5 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.

We are continuously receiving such feedback from the Community, and this project is intended to improve this situation by providing a new documentation architecture to the JSON Schema project.

🎯 Scope

The JSON Schema GSoD project will:

• Implement a new information architecture framework for JSON Schema.
• Audit existing JSON Schema documentation.
• Organize and refine existing documentation using the diataxis documentation principles.
• Create landing pages in the docs section to improve developer experience.
• Update README.md and CONTRIBUTING.md files to improve the onboarding experience for new contributors.
• Create a README.md for the github organization.

📈 Measuring success

We would consider the project successful if, after the publication of the new documentation:

• The docs page views increase by 50%
• The docs page bounce rate decreases by 30%
• The number of technical questions goes down by 20%
• The number of docs contributors increases by 3 Community members.

🗓️ Timeline

The project will take approximately 4-6 months to complete and can and may involve 2 technical writers.

Dates	Action Items
May	Onboarding and enablement
June	Audit existing documentation and identify improvement areas
July - September	Implement the new documentation framework
October	Write report, blog and release notes
November	Project completion

💸 Budget

Item	Budget	Notes
Technical Writer	5000.00	Standard rate
Technical Writer	5000.00	Standard rate
Total	10000.00

Additional information

Previous experience with technical writers or documentation: The mentors for the project are experienced with mentoring and the creation of documentation.

Current documentation:

• Site: http://www.json-schema.org/
• Docs: https://json-schema.org/learn/
• Github: https://github.com/json-schema-org

[Relequestual]

• Update README.md and CONTRIBUTING.md files to improve the onboarding experience for new contributors.
• Create a README.md for the github organization.

While these two tasks do need to be done, are the suitible for being part of the GSoD task list?
Have you seen similar tasks listed in projects from previous years?

[benjagm]

I think this a great opportunity to refine the onboarding experience and those docs are key elements in the user journey.