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 to our contributors guide if you plan on opening a pull request. For more details check out README.md file.

This section used We to address the reader instead of You, which is the right pronoun to use when writing for your readers.

While I would agree with this in a formal tech doc like a spec, this is informal and should be inviting. I think the pronoun use is fine, but it should be consistent.

The use of passive voice needs to be clarified for the reader about who is to perform an action.

What action? The user is reading docs. We (the author) aren't asking the reader to do anything.

I think make the pronoun consistent will be a good addition. Using "You" is ok for me.

Regarding moving the story of JSON Schema on top, we tried it but we decided to move it down because the goal of this page is understand the problem solved by JSON Schema and why both developers and organizations use it... We think is good information but not requires its own section as of now.

Having said that, when we wrote this page I was convinced about the goal and structure but today I dont think the result is as good as I expected. My suggestion here is to change the objective of the issue to focus in the whole page and rewrite and restructure it for clarity.

What is not working?

• I don't like the titles: "How it works" "The Challenge" "JSON Schema to the rescue" "Why developers use JSON Schema" and "Why organizations adopt JSON Schema" We can better highlight each section to improve flow and structure. I'd love the titles to inspire technical decision makers to use JSON Schema.

• Code description : We are abusing of the structure "In the above code snippet, we ...." We should find a way to explain what is JSON Schema and why is so important using code in a more natural way just as complement. We are being soo much descriptive when explaining the code ... that is not working

• The sections Why developers use JSON Schema and why organizations adopt JSON Schema requires an intro paragraph each and review every item to make sure the tone, is consistent.

• Next steps section: Seems uncompleted like we didn't have the energy or motivation to complete it ... this section needs an intro paragraph to better close the flow and and better redirect people to:

  • Try yourself by creating your first schema
  • Read the docs to learn more
  • Join the Community to get involved

@benjagm noted working on it

Additional information to be added

• under this section there should be a heading for the use case of JSON Schema
  What do you think?

@benjagm, I would also like to work on it.