Re: [docbook] document reviewing ideas

[Mats Wichmann <mats@wichmann.us>]

On 01/02/2014 02:28 PM, Norma E Emery wrote:
> Mats,
> 
> I run a PDF, enabled for commenting, and post the PDF in a central location where reviewers can take turns accessing the file and annotating it. We are also working on a feedback link for HTML output, but are not there yet. I then make the changes in the XML.

W3C has a little javascript jig which leaves a message in the upper
right corner allowing you to select text and then click to post a bug to
their bugzilla with some stuff including your selected text prefilled.
That might help your case, doesn't work for me in this instance
(bug-assist.js, you should be able to scrape it out of a W3C doc which
has it enabled, e.g.
https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/templates/index.html
and adjust it to send wherever)

> You say your "internal "customers" are used to reviewing with a wysiwyg tool (namely, Word) so they can markup and
> comment inline." 
> 
> I think this means that they like a "track changes" capability. If that is the case, what is it exactly that they like about this approach? Do they want the ability to, for example, Accept changes so that they can see how the revisions will look? It would be helpful to know why they like this method and what they want to achieve to determine the best solution.

It's a familiar tool to them, is the big deal. As reviewers they
wouldn't accept changes but they can change the display to one which
shows how the text would look if accepted.  I think the appeal though is
the ability to add comments which appear in bubbles, and secondarily to
be able to change text so that the change is marked up (strikeout/add).
 Convenience in dropping your ideas into the doc.

Yes, I am trying to avoid the excuse of reviewing being too cumbersome:
Oh, I have to write up "In section 5.2, Foo, second paragraph, change
Bar's to Bar is", I can't just click and fix it in the doc? But really,
I'm fishing for Best Practices, other people must have reviewing issues
as well.  I've worked on other projects where we kind of dodged it: "if
you have comments, please file a bug in our bugtracker", which isn't the
lowest-overhead user interface if you're honest.