Re: [docbook-apps] DocBook content review process/tools?

[David Cramer <david@thingbag.net>]

Hi Peter,

Good question. Here are a few ideas:

* Add a "Log a bug" link to each page that links to your bug tracking
system. It's usually easy to add a few query parameters that prepopulate
the new bug with contextual information (url, version, component, build
date, etc). Then the users only has to fill in a description and title.
With some more effort, you could add some code that queries the bug
tracking system and displays a list of open bugs against a give
chapter/section at the bottom of the page.

* Add some kind of commenting mechanism to the output. That
annotatorjs.org thing that Camille pointed out looks cool. I'm going to
have to check that out. Oxygen has a Webhelp with feedback chunked html
format. If security isn't a concern, then there are solutions like
Disqus that will add commenting to a page with just a little JavaScript.
Or there are open source and commercial commenting systems, usually
php-based, you can host.

* Oxygen XML has a "Content Fusion" product. I've only ever read the web
page and played with their online demo, but it uses a web-based version
of Oxygen to let users enter changes with track changes on. This looks
really cool, but if some of your content is generated programmatically
from more primitive sources, then you'd have to adapt the workflow to
merge changes to that content back into its original source.

* If pdf is your primary output format, Adobe has a feedback collection
system. I believe Acrobat Pro has to be involved. Perhaps this could be
automated if you produce postscript from your fo renderer and generate a
pdf from that using Acrobat Pro?

Regards,
David

On 10/23/18 11:53 AM, Peter Desjardins wrote:
> Hi! Does anyone have a document content review process you can
> recommend? One that allows non-DocBook users to easily provide input
> and see each other's comments?
> 
> My team uses Google docs for content review because reviewers can
> comment easily and see each other's input (this is at a company that
> uses Google email/docs). It's error-prone and tedious to transform
> DocBook content to Google documents though. I would love to find a
> better solution.
> 
> We keep content in GitHub and I love the pull request content review
> tools there. Most of our subject matter experts do not use GitHub
> though, and it's not practical to review all DocBook content by
> reading the source XML.
> 
> The conversion to Google doc format that works the best for us (so
> far) is DocBook > HTML > LibreOffice OpenDocument > Upload to Google
> drive and convert to Google doc format. We lose important formatting
> like bold for guilabel elements and bullet characters for
> itemizedlists disappear. Preparing a document for review is painful.
> 
> Do you have a great DocBook-based review process?
> 
> Thanks!
> 
> Peter
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
> 
>