5

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).

  • You might want to look into "Online Collaborative Word Processor" as a term to google. There are a lot more of them than there were when I last needed one, so I'm not qualified to recommend any particular one. But as a class of software, they allow you to post documents online then grant reading (and optionally editing/commenting) rights to individuals which you choose. – Henry Taylor Jan 25 '18 at 6:16
  • 2
    Just for clarity's sake: What you're essentially looking for is something that boils down to something much like the sidebar comments in Word or LibreOffice Writer, except that they should be stored natively within the HTML and require no external tools to be used by the reviewer (besides a web browser, I presume)? That might be a tall order to meet, considering general browser support for modifying files on disk... you'd probably need something server-side to at least store and retrieve the reviewer's comments. – a CVn Jan 25 '18 at 8:34
  • 2
    @MichaelKjörling that's correct; I'm asking about injecting commenting into the rendered HTML. This would require a server-side data store, which is fine (it's our server so we can do whatever we want there). Or maybe there's a better way; this is the idea I came up with, but I'm open to any improvement on "write it up separately in wiki comments". – Monica Cellio Jan 25 '18 at 15:09
  • What is the source format of your documentation? Is it HTML? – Alexander Jan 25 '18 at 18:52
  • 1
    @Alexander it's Madcap's schema, which is HTML with some add-ons for things like pop-outs, annotations, and snippets. – Monica Cellio Jan 25 '18 at 18:55
6

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.

  • 1
    Oh, injecting status and IDs/labels, instead of trying to inline the comments -- interesting idea! And much easier. – Monica Cellio Jan 26 '18 at 3:23
3

Not sure if I can adequately answer this, since I know little about web development. But I'll try to give some ideas.

I would use JavaScript to comment inline and SQL to store the comments.

  1. Double-click/select a word in the text. A comment box pops up. The user can type a comment and hit "OK". A comment (entry) is created, and the word gets highlighted. [Optionally you can let people choose to type of comment (e.g. spelling error or conceptual error).]

  2. An entry is created in the database: it stores the URL, the paragraph, the word(s) marked.

  3. Every entry gets its own ID.

  4. A script writes a marker with the ID to the HTML source.

  5. JavaScript opens the stored (marked) comments and allows to add a respond. You should probably also add time and author. Easiest would be to let the author write one's own unique name. Better would be having user accounts when doing the reviews.

Depending on your needs you can choose to display all the comments for that page on the right-hand side of that page. Or you could open a comment by clicking on a highlighted word.

I hope I could give you some ideas. Good luck!

  • 2
    Thanks. Do you know of any off-the-shelf packages that do anything like this (or parts of it)? – Monica Cellio Jan 25 '18 at 17:06
  • No, I don't. You could try a github search on javascript comments. – Boondoggle Jan 25 '18 at 17:20
2

Simple solution:

  • Commenters must refer to code by line number. A number (or range) is quick to type.

Easy solution:

  • Every line in the code is stored in a database as:
    Line number String
    4763 printf("Hello, World!");
  • In the Wiki, the line of code is clickable. When you click on it, a comment form unfolds under the line.
  • In the database, the comments are stored as:
    Line number Comment Comment author
    4763 lol John
  • When there are comments for a line, the Wiki displays the number of comments behind the link. This number is clickable. Clicking on it displays the comments under the line, clicking again hides the comments.

    All this should not take longer than an afternoon to implement for an experienced programmer.


You say that "[m]ost of our reviewers are not comfortable reviewing the HTML source". What then do they review? The rest of your question seems to say that your reviewers look at lines of code. Isn't that "the HTML source"? If not, explain.

  • They review the rendered HTML using a browser. There are no visible line numbers. If they were reviewing the raw HTML we could do something like what you describe using Bitbucket, git's web interface. – Monica Cellio Jan 25 '18 at 13:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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