Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
1 task done
valeriahhdez opened this issue Jul 18, 2024 · 5 comments
Open
1 task done

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

valeriahhdez opened this issue Jul 18, 2024 · 5 comments
Labels
📝 Documentation Indicates improvements or additions to documentation. GSoD Google Season of Docs Status: Available No one has claimed responsibility for resolving this issue.

Comments

@valeriahhdez
Copy link
Contributor

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:

  • Easy to find
  • Accurate
  • Relevant
  • Easy to understand

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

  • Could you find what you were looking for?
  • Was it accurate?
  • Was it relevant?
  • Was it easy to understand?

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

  • I agree to follow this project's Code of Conduct
@valeriahhdez valeriahhdez added 📝 Documentation Indicates improvements or additions to documentation. GSoD Google Season of Docs labels Jul 18, 2024
@github-actions github-actions bot added the Status: Triage This is the initial status for an issue that requires triage. label Jul 18, 2024
@valeriahhdez valeriahhdez removed the Status: Triage This is the initial status for an issue that requires triage. label Jul 18, 2024
@gregsdennis
Copy link
Member

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
Copy link

DevMhrn commented Jul 25, 2024

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

@gregsdennis
Copy link
Member

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

@harshsbhat
Copy link

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

@valeriahhdez valeriahhdez added the Status: Available No one has claimed responsibility for resolving this issue. label Nov 7, 2024
@Kashika23
Copy link

@valeriahhdez Can i be assigned with this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📝 Documentation Indicates improvements or additions to documentation. GSoD Google Season of Docs Status: Available No one has claimed responsibility for resolving this issue.
Projects
Status: Idea
Development

Successfully merging a pull request may close this issue.

5 participants