Annotation for doc review

[John Baldwin]

On Friday, July 04, 2014 4:54:42 pm Warren Block wrote:
> The phabricator instance has shown that some review can be done more 
> easily.
> 
> We've talked before about having periodic reviews of parts of the 
> documentation.  It turns out that experts rarely read the docs on things 
> they know about, but are the ones that can produce very valuable 
> feedback.
> 
> Phabricator probably does not lend itself well to reviewing our DocBook 
> documents.  The source and rendered versions are just too different to 
> review easily, even for those who are familiar with DocBook.
> 
> Ideally, we'd be able to show a rendered HTML version of the document 
> and let people comment on it.

Definitely agreed.

> There are commercial services out there for that, but also free 
> Javascript implementations that we could use directly, like this:
> 
> http://annotatorjs.org/
> 
> Note that I am not suggesting this would go on our documentation web 
> pages.  Instead, we would create a small rendered version of part of a 
> document, say one subsection out of a chapter, and put that up somewhere 
> for review and annotation.  At the end of a limited time, maybe a week 
> or two, the annotations would be gone through, adapted, and changes 
> applied.  Then the process is repeated for a different documentation 
> section.  The annotated web page is just temporary.
> 
> The biggest problems I see are
> 
>    user authentication: so we can avoid spam and vandalism, and track
>      suggestions by user.  For best results, this would use existing
>      credentials and not require creating a new account

Talk with clusteradm@ about the setup they use for bugzilla (and I
believe are going to adopt for phabric)
 
>    logging: annotations must be saved until they can be processed
> 
> If these problems can be addressed, we can make it doc review easy for 
> everyone.

This sounds like an excellent idea.

-- 
John Baldwin