Re: [docbook] document reviewing ideas

[Stefan Seefeld <stefan@seefeld.name>]

On 01/02/2014 03:57 PM, 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.

I know exactly what you are talking about, as I went through pretty much
the same process. (The icing on the cake for me was that the Object
Management Group, to which I submitted the specification, is actually
keen on structured documents, and was very supportive of DocBook, even
though in practice most of the world still submit their docs as MS Word
documents, which are then turned into formal specs by some in-house staff).

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

That's an interesting question indeed. I'm also not sure what would be
ideal here, as changing the sources doesn't seem appropriate either. It
probably depends on many other factors, such as how the sources are
controlled (version control ?), and whether the reviewers are technical
people who also author using DocBook, or whether they are merely reading
and feeding back comments / annotations.
What would be nice, but is probably overkill for most users, is a system
of externally held annotations as once was propagated by the Annotea
project (http://www.w3.org/2001/Annotea/). I have no idea what became of
that, though.

> 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?

Again, depending on the scale of your use-case (how many documents are
being reviewed, how many reviewers are working in parallel, etc.)
different approaches may work best. I have seen tools plugged into
websites, enabling visitors to leave annotations there. That made a lot
of sense for community projects (I think this was www.boost.org I'm
thinking of). Personally I have had people review pdfs and just annotate
those directly (and me incorporating changes back into DocBook manually).

DocBook 5 also has some vocabulary to store annotations, though I doubt
that that's appropriate for short-lived annotations that only a single
person (the author) will consume.

Regards,
        Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...