json-schema-org / website

JSON Schema website
https://json-schema.org
Other
64 stars 167 forks source link

[📝 Docs]: Change feedback form to actionable questions #805

Open valeriahhdez opened 3 months ago

valeriahhdez commented 3 months ago

What Docs changes are you proposing?

Instead of asking readers if the docs were helpful and allowing writing more details, which is sometimes filled with ambiguous statements, we need to ask questions that give us unambiguous, actionable information. Based on his research on readers' expectations from documentation, Yoel Strimling concludes the most important aspects for readers is that documentation is:

Based on this observation, Strimling recommends to ask four Yes or No questions to retrieve actionable feedback:

Screen Shot 2024-07-18 at 11 24 37

This proposal therefore suggests replacing the open-ended question Was this helpful? with the above questions. It leaves the opportunity to create an issue in case the problem our readers encounter is not covered by these questions.

Code of Conduct

gregsdennis commented 3 months ago

This needs to be coordinated with #762.

Good ideas here. We just need to be sure we're not losing the ideas in the other issue.

DevMhrn commented 3 months ago

I can make this form better , @benjagm should i start working on it ?

gregsdennis commented 3 months ago

The cue to start on something needs to come from @benjagm.

harshsbhat commented 3 months ago

Done! Created a PR for this issue please check it out. Thanks