Add topic to address, "As an engineer, how do I ask for feedback such that that which I receive meets my expectations?"

grafana / writers-toolkit

Technical documentation guidelines for Grafana Labs documentation

https://grafana.com/docs/writers-toolkit/

16 stars 12 forks source link

Add topic to address, "As an engineer, how do I ask for feedback such that that which I receive meets my expectations?" #46

Closed osg-grafana closed 4 months ago

osg-grafana commented 1 year ago

There are many types of feedback, and if our expectations are unaligned, unintended friction can arise.

This issue covers the various types of feedback, as well as the timing of feedback. It also addresses the circumstances where feedback that technical writers provide is not incorporated: if a product needs to go out immediately and the documentation is deemed lower priority for the time being, that also benefits from aligned expectations.

osg-grafana commented 1 year ago

Hey team! Please add your planning poker estimate with ZenHub @brendamuir @chri2547

GrafanaWriter commented 1 year ago

We can create content that covers best practices for feedback; the type of feedback is often driven by deadline:

Large edit: developmental edit (typically for draft PRs) - suggest changes and here's why - further dialog required -Medium: basic edit: here's my suggestion and here's why - no further dialog required
Small: copy edit (if the Vale linter is not enabled in the repo): here's my suggestion, no discussion of background or rule except general pointer to the Style Guide

jdbaldry commented 5 months ago

Are we still interested in this documentation? Are we seeing the mismatch of expectations in practice?

imatwawana commented 5 months ago

I'm not sure if there's a strong need here. I don't think I've really run into this issue. I think we probably have a stronger need for socializing people using the office hours to get help if they don't have an assigned writer. My $0.02.