Documentation site not as helpful as it once was

[jsumners-nr]

I have been away from work that requires understanding JSON Schema(s) for a couple of years, but just encountered an item where we decided to utilize it. As part of reviewing it, I wanted to reference the documentation and learned that there is a "new" JSON Schema documentation site, and I do not find it very helpful at all.

https://web.archive.org/web/20221224225320/https://json-schema.org/understanding-json-schema/ has been my go to for reviewing schema concepts, and I cannot find the equivalent on the new site. In fact, the old overall docs are still MUCH easier to navigate in my opinion. I really cannot figure out how to even find relevant information on the new site.

[github-actions]

Welcome to the JSON Schema Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look at our contributors guide if you plan on opening a pull request.
For more details, check out the README.md file.

[jdesrosiers]

Sorry for the difficulties. The content from Understanding JSON Schema is still there under https://json-schema.org/understanding-json-schema. The styling and navigation is different, but the content is still the same.

You might find https://www.learnjsonschema.com a more accessible reference.

[jsumners-nr]

The styling and navigation is different, but the content is still the same.

Good to know that the text still exists. All I can say is that it is far more difficult to find and then actually read. Consider:

1. https://web.archive.org/web/20230116020913/https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values
2. https://json-schema.org/understanding-json-schema/reference/enum

The current page requires scrolling for this very short section. The original fits all of the necessary information in view, and doesn't necessitate loading a completely separate page to view any of the other related material.

You might find learnjsonschema.com a more accessible reference.

Not really. I very specifically linked the archived site because the page I linked has always been a fabulous, easy to navigate and read, summation of the spec and how to apply it. On this new domain, it's not clear what applies to the thing I'm interested in and is more concerned with documenting the spec for spec authors than for users (e.g. the description for enum is a singular sentence that is easily overlooked due to the massive metadata block grabbing attention from it). For example, today I wanted to verify how to limit a string field to certain known values. The original site very clearly labeled the string type and everything associated with it, and it clearly outline keywords that are applicable to multiple types (e.g. enum).

[benjagm]

Thanks a lot for this message @jsumners-nr . We changed the structure because Understand JSON Schema was created more like a book, and we intended to structure the content more like developer docs that we can scale and evolve more easily. Having said that, it is highliy possible that some of the changes in the navigation are not working as expected. Can you please provide some examples? I would love to have those changes implemented to keep the documentation useful as it was and escalable as we want it to be.

[jsumners-nr]

Can you please provide some examples?

What sort of examples are you looking for? My assertion is that this new design is not helpful to someone looking for easy to read and reference documentation in comparison to the original design.

[benjagm]

Hi @jsumners-nr. English is not my mother language so I probably didn't express my request properly. Let me start again.

In this issue you are sharing your experience with the new content structure highlighting that information is now more difficult to find and reference providing and example with Enum related docs and my comments was If you have some other examples of suboptimal search experience. This can help us think on a better solution.

For your information. The content is basically the same, we just tried to organize it in a way that works better for consumption and contribution. See details here. If we find that some of the changes are not working as expected, we can adjust them using feedback from the community, including your feedback.

I hope this helps.

[jsumners-nr]

I am saying that the issue you linked completely misses the point of easy to read and reference documentation. All of the suggestions within it have been implemented and resulted in this issue. Menu diving is far more difficult that looking at a simple table of contents. Clicking through multiple pages is far more difficult that a simple single page.

There's nothing "broken" about the current navigation. It works as intended. I'm just saying that it is harder to use and access the information than when the site was simpler.

[benjagm]

Thanks for providing more details. Let me create an issue to build a page with the table of contents to improve that experience.

Could it be a solution if we replace this page with a standard table of contents? https://json-schema.org/understanding-json-schema/reference

[jsumners-nr]

Maybe. But, for me, the whole design is just not as effective as the original.