Re: [docbook] document reviewing ideas

[Philip Fearon <pgfearo@googlemail.com>]

A short while ago I looked into the problem of visualising XML
document revisions made in parallel by several reviewers. Changes made
in parallel can be complex to resolve because they may conflict, but
parts of them may also coincide (intentionally or otherwise). Changes
made at the text or element level also need to be differentiated.

I came to the conclusion that ideally you need to provide a number of
ways to view that changes - ideally with a WISYWIG view synchronised
with a source view. For example, you could have a document view that
can show either all revisions together, with perhaps one reviewers
changes highlighted, or alternatively, when you hover over marked
changes it shows you the reviewer(s) responsible for those changes. An
alternate view would show you the document with each reviewers changes
applied as you select the chosen reviewer. I wrote a short blog
'Reviewing XML Documents for an N-way Merge' on this and a prototype
web app to try out some ideas - because much of the behaviour required
is dynamic - the blog is at:
http://blogs.deltaxml.com/2013/08/22/reviewing-documents-for-an-n%E2%80%91way-merge/

This approach requires that reviewers modify the source. Whilst this
might not sound ideal for reviewers unfamiliar with docbook (I
actually used DITA in my sample but many concepts are the same for
both), if the changes are just text based (corrections, deletions,
clarifications etc) then they should find they have few problems so
long as they use a decent XML editor. The next stage of course is
selecting the required changes and merging them in to the original
document - but this can be a lot simpler than understanding exactly
what changes have been made and where the conflicts lie.

Back in the day when I participated in formal document reviews, we
simply reviewed the rendered document and, in a separate form,
recommended the changes required (in plain text using section/para
numbers - and where it wasn't obvious - giving reasons for the change.
The document 'owner' would then take an age to respond with a new
version for review along with a modified version of the form saying
which change requests had been rejected and the reason - hardly ideal.
This isn't exactly relevant - but I did find that a good 'product
description' was essential when performing a review because all change
requests would be made in this context (with the product description
stating what the purpose of the document was, who it was for, and what
the reviewer's roles were).

Phil Fearon

On Fri, Jan 3, 2014 at 7:52 AM, Camille Bégnis <camille@neodoc.biz> wrote:
> Hi Mats, all,
>
> we have implemented in our XML CMS (http://www.calenco.com) a feature that
> allows to do exactly this, and more.
> Basically that systems offers the users an HTML Web Form of the XML
> Document. Specific fields, identified by the XML author, or automatically
> added by the XSLT transformation, are displayed under the form of input
> fields (text fields, check boxes, etc.).
> Then all data entered by users on the Web interface is injected back into
> the XML document.
> An automatic locking mechanism ensures 2 different people cannot modify the
> same document part at the same time.
>
> That allows to provide any user with a very easy interface to comment or
> approve a document, with just a web browser.
>
> This feature is not available in the Free version of Calenco, but I'll be
> glad to discuss of a possible POC with you.
>
> Best regards,
>
> NeoDoc
> Camille Bégnis
> camille@neodoc.fr
> Tél: +33 (0)4.42.52.24.20
> 5, rue de la Touloubre
> 13770 Venelles
> France
> http://www.neodoc.fr/
> On 02/01/2014 21:57, Mats Wichmann wrote:
>
> A little backstory here...
>
> I inherited a specification document that was written in MS-Word.
> Although not my preferred format, existing institutional familiarity
> meant I didn't initially have the option to change.  However, when the
> project evolved and it became clear I'd have to produce a half dozen or
> more variants of the document, while maintaining large chunks of the
> content as common text, I went ahead and did the conversion to docbook
> to maintain some semblance of my sanity.
>
> The problem I now have is my existing internal "customers" are used to
> reviewing with a wysiwyg tool (namely, Word) so they can markup and
> comment inline. Turns out I haven't had luck generating stuff Word can
> read directly, but it comes out at least acceptably if you feed it html.
>  However... it doesn't seem ideal to convert to another format for
> reviewing, then have to "backport" things to the master. This might be a
> case for the roundtripping stuff (dbk2wordml) but I can't get a usable
> doc out of that at all.
>
> So... asking for advice.  What do people typically do when it's time to
> pass a document around to multiple reviewers?  I'm not convinced
> something like Word is the best answer even there (you end up having to
> review serially, not in parallel, or you'll go nuts reconciling the
> comments in multiple different docs, but it's certainly comfortably
> familiar to folks whose companies run on MS-Office).  Is there a "better
> way" that ties in well with having sources in docbook?
>
> -- mats
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>
>
>