How to Give Good Feedback

An important part of making documentation useful for the community is getting community feedback on it; we want (as a community!) to make sure that we agree on the content of the documentation, and that it will help members of the community add to their skills and understanding.

If we are building a document for novice users, we want to make sure we don’t overload them with details and corner cases. Learning is a process that takes energy and time, and it comes in steps.

If we are building a document for expert users, we can start to take shortcuts: we can make assumptions about what our audience already knows, use jargon, or make references to specific knowledge. Expert users are likely to be task driven (“what was the specific kind of tooling I need for this again?”) and will approach the documentation looking for details.

We must be very careful about managing audiences. The above two audiences have very different needs, and building a single document to support them both is very difficult. We will likely want different documents. What we want to avoid is accumulating expert knowledge in the novice document: that won’t help the novices, and will annoy the experts.

A good place to start with feedback is to:

• Comment on things we want to fix
• Comment on things we want to keep
• Comment on things that we notice or remember

When commenting on things we want to fix, it can be helpful to say why - it could be that the information is slightly wrong, or dangerously wrong. Knowing more about the context and extent of the wrongness can be very helping in finding a better solution.

When commenting on things we want to keep, it can be helpful to say why: these comments can illuminate multiple points of view, and knowing about them can help authors preserve content that is valuable to audiences the authors might be less familiar with.

Commenting on things we notice or remember can be very valuable to authors: some part of the document may be drowning out something else which is important.

A category of comments that may not help much are comments like:

"Who told you this?"

or:

“Where did this come from?”

• If our purpose in asking this is to make the documentation better by removing broken information, we are already doing that by revising the documentation. The focus is on improving this version, not previous versions.
• If the source is other documentation or media, it might be worth flagging the source as questionable.
• If the source is a person, we may want to check in with that person to make sure we are all on the same page (they may have previous experience or other resources that add additional insight).

Regardless: the mission is to improve the current documentation.

If our purpose in asking this is to find the sources of the information and punish them, that does not help. We don’t do that.