Post History

Source: https://writers.stackexchange.com/a/32802
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/32802
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

On one project I worked on, we did reviews via a work- in-progress server, which was an HTML version of the current state of the docs. We created a modified build script for this server which included the following:

- A status indicator for each topic (ready to review, draft, final, etc.)
- An ID for each topic.
- Paragraph numbers in each topic.
- An instruction to raise any issues found, in review or otherwise, in the issue tracking system using the topic ID and paragraph number. 

This was relatively low tech. Commenting did not happen in the docs interface itself. But it seemed to work well. Reviewers had an easy way to indicate what their review comments applied to. I think they tended to review with a text editor window open and made comments by paragraph number, then pasted it into the error tracker. These were all operations they were well used to doing, so there was no learning curve or unfamiliar tools to use.

The work in progress server was live all the time that the docs were being developed, with appropriate status notifications on each topic. We found that a number of people in the organization found it useful to have this information available during development and we occasionally got feedback outside the formal review process.

Original score: 6