8

Draft technical documents can be reviewed by stakeholders. Stakeholders can be fellow practitioners, industry specialists, senior managers, regulators, and so on.

The purpose of a stakeholder review is usually to receive feedback in the form of comments. The comments can be compiled by whoever is managing the documentation project and be used to improve the document prior to publishing.

Comments have traditionally been collected on a comments form that is supplied with a draft. Comments can also be returned as notes attached to a PDF.

These methods have a low barrier to entry and are useful for a wide-reaching review. But these methods are becoming obsolete as content is developed on the web.

What is the best modern practice to collect comments on a draft?

Improve this question
1

5 Answers 5

Reset to default
6

As Chenmunka says, there are many systems that will provide a "place" to review the content. As for the actual process, I think that depends on where you content starts. Is it in MS Word? Then Chenmunka's suggestion is probably the lowest effort and best method. A slightly more "modern" alternative might be Google Docs.

If it's structured (XML/DITA) or web focused (Markdown), then you have a lot more tools to choose from. Many documentation systems come with review mechanisms. The way these mechanisms are implemented vary widely, so be sure to really test them before implementing one (I'm a huge fan of POCs).

Another option is using a staging site. If you're publishing to a knowledge base, wiki, or web CMS, most of them will have some feedback mechanisms built in. If you run a staging site you can use it as a place to review content before that content is published to the live version.

In the end, you need a central place to collect comments. Ideally, this place is very close to the source content, because that's going to be the primary determining factor in how much work it is for you, as the technical writer.

Improve this answer
1
  • I find that using an online system, such as Google Docs, is really easy for stakeholders to add comments. This, of course, assumes that both you and the stakeholders have access to the tool.
    – Kimberly Lacerte
    Commented Jan 24, 2018 at 15:45
1

You can use a cloud document system such as Microsoft's Sharepoint or one of the similar competitors.

Publish your document there along with the comment form template and then you can either:

  • Allow reviewers to complete the form offline and upload their version to the site
  • Allow reviewers to complete the form online

With the likes of Sharepoint you can restrict access to stop the reviewers from seeing each other's submissions. This is especially useful if the reviewers are from outside organisations. Or, if allowing online completion you may wish to have just one comment form which all can see.

This is more controllable than, say, putting an editable version of your document online and having reviewers add comments within it. You have a number of received, identifiable comments that can be referenced and audited against as necessary.

Improve this answer
1

Inline comments where reviewers can reply to each other and everyone gets email notifications of updates work the best for me.

Confluence's implementation is the best I've used, but it has the weakness that the inline commenting feature is invisible until you select the text you want to comment on. Reviewers who don't know to do that stick with comments at the bottom of the page instead, which is somewhat less efficient.

Google Docs' implementation looks similar, but the workflow isn't as elegant. I often have trouble finding which comment an email notification relates to and questions often get left unanswered. (More generally, Google Docs has the same problem as Word in providing far too many formatting options for casual users, so if they have edit permission the doc is likely to end up a terrible mess.)

Acrobat / Adobe Reader shared PDF review seems similar but due to network issues I've never been able to get it to work. I'll take it over Word any day if comments are provided over email.

Improve this answer
1

A meeting of all stakeholders on a regular basis with concrete action steps agreed (i.e redraft x, review by person y.) can be effective.

Improve this answer
0

GitHub provides an inline comment feature which is pretty neat to facilitate reviews, as well as promote discussion among developers about the content and the comments.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.