Saturday 8 June 2024

Commenting guide for collaborative document reviews

Cartoon of a document reviewer.

After thousands of collaborative documentation reviews, from our Good Docs Project technical writers, we have established a bunch of practical tips for providing good feedback on documents. We’ve collated our collective wisdom into a commenting guide for collaborative document reviews. It includes:

  • Tips for reviewers to convey useful and actionable comments, which don’t mess up the original document.
  • Tips for authors, to attract useful feedback, and resolve comments cleanly and respectfully.

This guide will be useful for any teams working with doc tools which support track changes, like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab.

Thanks to the many Good Docs tech writers who helped collate and refine this guide.