Post History

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

Summary: I'm looking for a way for reviewers to comment collaboratively as close to "inline" as possible on a large HTML project.

## The problem in detail

I work on a team that documents a large product. The HTML documentation set has hundreds of individual pages (with sidebar hierarchical table of contents, as you would expect); a PDF of the entire doc set is 5000+ pages.

When we document a new feature or make broad improvements like reorganizations, we publish an HTML build for review by developers, QA, support, the product manager, and other writers. We publish the entire doc set in this build, not just the changed pages, because sometimes context matters. To mitigate that, we provide links to the specific topics that changed. We actually add these links to the doc plan, a specification that we produced earlier describing the intended changes -- this way people can, if they want, see the background of _why_ we made a particular change. The doc plan is a page on the internal wiki.

Right now, when we send out a review request, we point people to that wiki page, and ask people to post their feedback as comments. This allows everybody to see each other's feedback, which means (a) less repetition compared to individual responses and (b) earlier discovery of disagreements among reviewers. But long comment chains can be hard to navigate too, even with threading. And people still have to do some extra work to write those comments, because they have to tell us what they're reacting to. Typical comments begin with something like "in 'Installing Plugins', the description in the third paragraph isn't quite right because...".

This approach works better for us than either email responses or individually commenting on PDFs of just the selected topics. (We've done both of those.) Is there a way to make it even easier by allowing people to attach comments right there in the HTML, kind of like commenting on Google Docs, but without having to import our large doc set into some other tool just for this purpose? Or is the current approach the best we can do without a lot of extra work?

We want to make it easy for people to comment and see others' comments. The bar to beat is comments on a wiki page. We aren't interested in importing a large HTML doc set into some other tool (that people would have to learn). I'm wondering if there's, say, some Javascript package out there already that we can inject into these builds to support this goal, or some other way to achieve this goal.

## Tools in use

We use source control (git), with feature work being done on branches. The review builds are produced from those branches and are persistent. (Most of our reviewers are not comfortable reviewing the HTML source, or I would sidestep all of this by having them review the raw source on the branch.)

We use Madcap Flare to create and build the docs. Flare's schema for the doc source is an extended HTML; all HTML is valid, plus they add some tool-specific tags that are used at build time. The output is conventional HTML.

We use Jenkins to manage the build process. Jenkins currently calls a script that does some housekeeping and invokes madbuild.exe (Flare's build engine). That script publishes the HTML on an internal server. In principle, therefore, we could modify the build script to inject something extra into the output just for these branch builds. We own the server, so we can add things to it if needed (like a way to store comments).

Original score: 5