System
Light
DarkUpdate from the Google Season of Docs 2024 Project
Go back to blogThe JSON Schema documentation project
The main goal of JSON Schema's documentation project is to create a scalable documentation architecture that is clear, consistent, and comprehensive. To achieve this through Google Season of Docs (GSoD), we focused on:
- Restructuring the specification docs: The specification docs need a structure that helps all personas understand how JSON Schema has evolved across different releases and the features introduced in each version.
- Revamping the information architecture: The documentation needs a new information architecture that better aligns with the documentation developer journey and organizes content based on the diataxis framework. The new information architecture's goal is to improve the onboarding experience and content findability.
The GSoD project accomplishments
Since May, the team (Valeria Hernandez, Blessing Ene Anyebe, Dhairya Amrish Majmudar, and Benjamin Granados) has been working hard to achieve these goals. On the part of documentation, we have completed the following:
- Conducted a thorough content audit
- Mapped out the developer experience journey
- Implemented the keywords page
- Restructured the specification docs
The team has also introduced changes to the website, like a table of contents and a Next-Previous component that aim to improve content scannability and navigation.
The road ahead
So, what's pending? We're currently working on the JSON Hyper-Schema and Migration pages, which are part of the specification docs.
We're also documenting guidelines for docs contributions and text formatting, documenting missing keywords (see issues 951, 952, and 961), and writing step-by-step guides (see issues 180, 950, and 954).
Conclusion
Our documentation efforts are expanding daily, and your contributions can improve them. There are several ways you can help, including:
- Breaking down large documents to improve the overall structure of the documentation website
- Creating missing documentation for the Troubleshooting and Scaling stages of the developer journey
- Contributing to the Migration page
Our docs meeting is held bi-weekly every Tuesday at 3:00 PM (UTC). You're welcome to join the #gsod24 channel in the JSON Schema Slack workspace and send us a message with your email address so we can add you to the meeting.
We appreciate your interest in the JSON Schema documentation project and look forward to your contributions and their benefits to the wider developer community.
The JSON Schema's Google Season of Docs Team.