Complete and publish the new website

[benjagm]

Context:

JSON Schema has been successfully using the same website for many years. However, it has become outdated with time, providing a suboptimal developer experience. This is the reason why the past year JSON Schema invested in the development of a new website. Although the development has been completed, there are still some pending tasks to be able to roll out the new site.

The new website is available in the repository: https://github.com/json-schema-org/website

Work Detail and status:

We have created this project to track all this project activity and make it easier for others to contribute:
https://github.com/orgs/json-schema-org/projects/11

The development version of the new site can be accessed here

Table of contents:

1. People working on this
2. Content buckets
3. Personas
4. Good examples of Landing pages
5. Prototype
6. New Docs Structure

People working on this

• UX/UI - Paul Waller : (Thanks to Endjin / @mwadams)
• Technical Writing : Melinda Guthermuth (Thanks to Postman) ad Akanksha Kushwaha.
• Frontend : Roni Lockwood (Thanks to Postman)
• Backend / roll-out / Project facilitation : @benjagm

Content buckets

1. Specification Section with the last JSON Schema specification and access to the previous releases. This section may be easily included inside docs with a proper taxonomy.
2. Docs Section with all docs, tutorials and resources. Probably we'll need to include the roadmap
3. Implementations Section with all JSON Schema tooling
4. Blog Blog section
5. Community Community section

Personas

The following personas are representative and they will evolve.This is a living document.

First-timer Schema developer

Characteristics

• The project can be personal or job related. If the project was job related, this persona has been assigned with the task of developing schemas and/or integrating or developing JSON schema tooling.

Primary goals

• Needs to quickly develop JSON Schemas for an specific project for the 1st time
• Need to learn JSON Schema and get support from experts

Frustrations/pain points

• JSON Schema is difficult to understand and docs are unstructured, outdated and difficult to find

Architect / Technical Lead

Characteristics

• This person is the decision maker to integrate JSON Schema in a Project/Organization.

Primary goals

• Evaluate JSON Schema production readiness, and the project sustainability.
• Make sure the technology is easy to adopt. Evaluate docs and support.

Frustrations/pain points

• JSON Schema is not production ready (Draft naming). I don't know what big companies are using JSON Schema.
• Not sure about trusting on unknown implementations, sometimes supported by one single person.

Experienced Schema developer

Characteristics

• Experienced developer
• Feels some sense of ownership over the project ("I want to share this with the world")
• Extensive schema experience
• Sees self as ultimate decision maker
• Has good community reputation
• Has open source experience

Primary goals

• Be up to date with spec, tooling and use cases
• Help others and increase networking. Increase reputation

Frustrations/pain points

• Not enough time to get involved in Open Source
• Low quality of docs
• Backwards compatibility in the specification evolution. Costs of evolving schemas
• Find ways to get involved and support the community/project growth.

JSON Schema Implementer

Characteristics

• Experienced developer
• Feels some sense of ownership over the project ("I want to share this with the world")
• Extensive schema experience
• Delivers specialized open source tooling

Primary goals

• Provide great developer experience and solve users problems
• Keep independence from Open Source Orgs.

Frustrations/pain points

• Low resources to evolve their implementations.
• Backwards compatibility in the specification evolution.
• JSON Schema is not offering incentives to evolve implementations nor ways to get involved while maintaining their independence.
• JSON Schema does not provide specialized resources for implementers.

Corporate entity

Characteristics

• Companies using JSON Schema. or evaluating its use or recognizing its value.
• Likely feels some sense of ownership over the project ("We are open sourcing this project to the community")
• Cares about fostering a healthy community.

Primary goals

• Improve brand and reputation
• Grow a platform (get people to use it)
• Stability and sustainability of the project they are using or investing on.

Frustrations/pain points

• Low quality of the website. Low brand recognition.
• Visibility of the strategy, roadmap and governance.
• Visibility of the community metrics/health/growth.
• Low awareness.
• Is this production ready?

Landing pages to consider as good examples

• https://argoproj.github.io/
• https://www.asyncapi.com/
• https://backstage.io/
• https://grpc.io/
• https://istio.io/
• https://www.crossplane.io/

Features to include in landing page

Main Section

This is the main section with Value Proposition and main call to actions. This is the 1st thing a new visitor will see. I suggest here a similar approach than AsyncAPI with 2 links to docs and search because docs and content discoverability is our main pain point.

Why Section

With this section we intend to generate trust in new visitors by highlighting benefits for all the personas: schema developers, implementers, contributors and Organizations.

Tooling Ecosystem section

This section is extremely important. This highlights that the JSON Schema ecosystem is huge. JSON Schema is not only the specification … There are hundreds of implementations out there.

This section is very important to implementers personas. We'd like to make them feel that they are part of this and we take care to recognize and provide them visibility and resources.

Community section

Section dedicated to Community…. Channels, events, how to contribute.

Sponsors section

Section dedicated to Sponsors. Important to Corporate personas. We are looking to engage with enterprise and organizations.

Trust section

This section will help to demonstrate that JSON Schema is a production ready technology widely adopted by well known orgs. In the future we will add uses cases and testimonials.

OpenJS section

Section dedicated to highlight that we are part of OpenJS Foundation. This will generate trust.

Google slides version here

New Docs Structure

Available here: Improve Docs and Spec navigation

[benjagm]

Some additional items than can be added in the future:

• https://www.learnjsonschema.com/
• Build a JSON Schema Landscape website#144

[benjagm]

Related issue json-schema-org/website#235 : Who is using JSON Schema - Logos Companies.

[gregsdennis]

Is there a preview for the site anywhere (like how we preview the blog in PRs)? I shouldn't have to be able to run it locally to see it. And I don't think I've seen the proposal yet.

[benjagm]

Is there a preview for the site anywhere (like how we preview the blog in PRs)? I shouldn't have to be able to run it locally to see it.

it is possible to run it locally by following the instructions available here: https://github.com/json-schema-org/website#readme

The content of https://github.com/json-schema-org/website is what the vendor left us the past year. Of course the style looks renewed, but overall the result is suboptimal and the content is mixed and wrongly structured. This is the reason why instead of just releasing it, we are working in improve docs, content taxonomy and a new landing page among other things.

[gregsdennis]

it is possible to run it locally by following the instructions available here: https://github.com/json-schema-org/website#readme

I know it's possible to run locally, but I shouldn't have to be able to do that.

[benjagm]

I know it's possible to run locally, but I shouldn't have to be able to do that

I wasn't aware of any preview option of the blog. Happy to do something similar here.

[Relequestual]

Is there a preview for the site anywhere (like how we preview the blog in PRs)? I shouldn't have to be able to run it locally to see it. And I don't think I've seen the proposal yet. - @gregsdennis

I have assumed we will host this new site on cloudflare as opposed to netlify.
Over the time that we've used both (netlify for the main site, cloudflare for the blog), netlify has prooved to be less stable.

Both serviced provide PR build previews, however cloudflare will ONLY do so from a branch in the same repo, and not a fork. They have no plans to make this possible.
We COULD use netlify for build preview only (which we do for the blog iirc), however there's a potential for missmatch (problems in one but not the other), which I think has actually happend once.

We could sidestep this with automation, where an action is triggered on any PR to clone the branch on a fork into the repo. But we would then either need to manually trigger a deployment (possible via API calls. Deploy to a Cloudflare "pages" domain, and treat it as a preview), or create a new PR to trigger the deploy preview. It doesn't seem we can manually trigger a deploy preview.

It does start to get a little fiddly though. I'm not sure on the best solution here.

EDIT:

Having asked again on the Cloudflare Discord, it may be possible to use the pages-action GH action as opposed to the GH Cloudflare app for deployments, and as such, enabling (I'm told) deploy previews for forks.
We would probably need to make sure it doesn't run for new contributors until enabled. That's already happening for some other action/workflow we have defined.

Let's add a new issue, if it doesn't already exist, to create the production setup on Cloudflare =]

[benjagm]

To know the current status please check-out the project we have created available here:
https://github.com/orgs/json-schema-org/projects/11

[benjagm]

We can close this issue.

[Relequestual]

🥳