2024 Google Season of Docs Case Study: JSON Schema

[benjagm]

Organization or Project: JSON Schema

Organization Description: JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. We are a community JSON Schema enthusiast dedicated to maintain, evolve and promote the JSON Schema specification. The Community consists of individuals, community members, tooling builders, schema designers, researchers, tech writers and representatives from companies and organizations who use or are considering using JSON Schema.

Author: @benjagm

🤯 Problem Statement & Proposal Abstract

After 10 different releases over the last 15 years the JSON Schema specification has turned in a very complex document too much focused on tooling creators but difficult to understand for general JSON Schema users. To close this GAP, the community has been creating a set of different documentation resources including a book, specification release notes, and some examples however those resources have proven to be insufficient to provide a good onboarding and learning experience for developers.

We already started the work to improve this situation adopting the diataxis documentation principles, defining our docs vision and delivering the documentation strategy, however we need technical writing support to be able to solve the core problems of our docs.

note: 2024 JSON Schema GSoD proposal

📝 Project Description

The JSON Schema 2024 Google Season of Docs (GSoD) proposal was originally proposed by @benjagm to the community in late 2022 via an open GitHub public discussion and based on the feedback and considering the problem statement we ended up focusing on those 2 projects:

• Project 1: Rebuild the JSON Schema Specification docs
• Project 2: Rebuild the JSON Schema Reference docs

💸 Budget

JSON Schema requested from Google a total US $10,350 budget for both proposed Docs projects. (i.e. $5,000 per project plus $350 for swag) .

Budget item	Total Amount
Technical writing for the Specification Project	$5,000
Technical writing for the Reference Project	$5,000
Swag to award selected participants	$350
TOTAL	$10,350

👩🏻‍💻 Participants

Of the 100+ candidates that applied, I (@benjagm) interviewed 30+. In the end, we hired 3 candidates to collaborate with us for GSoD this year: @kwennB, @valeriahhdez, and @DhairyaMajmudar.

The following factors were considered when selecting candidates:

• A humble attitude that actively listens and incorporates feedback.
• Strong collaborative abilities.
• Open Source experience.
• Technical writing experience and passion.
• Editing experience and approach.

⌛ Timeline

Here is a short overview of our timeline:

Dates	Action Items
May	Onboarding and enablement
June	Audit existing documentation and identify improvement areas
July - September	Implement the new version of the Reference docs
October-December	Extended wrap-up works
December	Project completion and GSoD contributors receive some swag

🙌🏽 Deliverables

Planned deliverables

Deliverable	% Complete
Rebuild the JSON Schema Specification docs	95%
Rebuild the JSON Schema Reference docs	95%

We are still completing some of the work because of some delays during the summer. The core reason for this delay is because several members of the TSC were affected by a layoff which impacted heavily their availability to support the project.

🔎 Analysis

What went well

Despite being a few weeks behind in the timelines, we're pleased with our significant achievements. The hiring process proved to be a great success as the participants showed huge resilience and professionalism in securing the project's success. The Tech Writers are now leading the Docs Working Group which is a clear symptom of success.

Challenges

Hiring Process

We tried an open application process providing everyone the chance to interview with the hiring person, but due to the huge number of applicants, this ended up being an overwhelming process requiring to change it while the process was still open. Unfortunately, a standard approach for CV screening would be necessary next time.

External Factors

Several members of the TSC were affected by a layoff this summer which was a big risk not only for Google Season of Docs, but also for the whole JSON Schema project. Fortunately, the community is so strong and after some weeks of adjustments, the Project is now even stronger. Those hard weeks during summer required a lot of resilience and determination from the Tech Writers and they an amazing job navigating all that ambiguity.

👉 Appendix

Join JSON Schema Community
Contributing to JSON Schema