How to Give Better Documentation Feedback


Most technical writers have a complicated relationship with feedback. We have the desire to make things better, but it can be difficult when our documents become personal. Each year the STC Competitions provides a way to obtain the feedback we desire in order to become better writers.

This past year I entered an internal DITA resource in the STC Carolina Chapter Competitions. I knew it had its flaws, but I wanted to see if other writers agreed with me and (hopefully) found some things I didn’t. The feedback I got wasn’t what I was expecting, and no one mentioned any real problems.

Many of us simply don’t know how to give constructive criticism that is specific enough to be helpful. Here are some ways to give better documentation feedback.

Critique, Don’t Edit

STC judges are reminded that judging does not mean editing. When providing feedback about a document, focus on the entire document as it’s intended to be used. If you notice writing mistakes, provide that as one item in the feedback (with specific examples of course).

Know the Difference between Praise and Criticism

Many conflate “criticism” with “negative feedback.” You can be positive without resorting to simple praise. Here are some examples:

Praise:  The images and text work very well together.
Constructive criticism:  I’ve noticed that a few of the images and text don’t work contextually together. (Remember to give examples.)

Praise: The document is usable and easy to read.
Constructive criticism: The document’s usability could be improved in the following ways…

You can be positive while also accentuating the issues. This is the type of feedback writers are looking for.

Note: The “Sandwich Method” is Unnecessary

Being positive when giving criticism doesn’t mean that you have to “soften the blow” with praise. Whenever I get a criticism sandwich–praise, criticism, praise–I just want to roll my eyes. We’re not children; we should be able to handle the criticism on its own.

Give Specific Solutions to Specific Problems

If you see a document that needs more than just a professional edit, call out specific problems and ways to address them. For example:

General: The pages feel a little cramped.

Specific: While the images are contextually appropriate, I feel they could use more surrounding white space. The current space between the text and images makes the page feel more cramped and therefore slightly harder to read.

General: Your font choices are appropriate.

Specific: The heading and body fonts you chose are great for this document because they are large enough to read and provide enough contrast. Nothing is distracting about the words, and it makes reading this document more pleasurable.

**Note: Although many of us have no control over our corporate style, when several people agree that something isn’t working, it’s easier to get those style choices changed. Similarly, disagreements in the author’s group might be helped if their style choices are validated this specifically.

General: The content is not adequate for the intended audience. (Whoa!)

Specific: The document is targeting novice users, but I feel that it needs more introductory material to help orient beginners. For example, the product overview should include more than just features, but what the user can do with those features. Also consider a “Getting Started” chapter to include this information that more advanced users can skip over.

Focus on the Document, not the Person

Feedback is personal, but the author won’t feel attacked if it’s presented the right way. Focus on the document, not the person who wrote it, and remember to be compassionate.

Personal: You need to edit your document.

Not personal: I’ve noticed some typos and a few minor grammar and spelling issues, so I recommend having someone proofread the document before publishing.


One Response to “How to Give Better Documentation Feedback”

  1. Very well said! I’m sorry you didn’t get useful feedback from the STC competition judges. Apparently we technical communicators struggle with this just as our SMEs do. I hope that a lot of them will read this blog post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: