[annotator-dev] Using annotator.js for HTML doc review

Thu Jul 24 16:40:32 UTC 2014

Hello.  I'm a documentation committer with FreeBSD, 
http://www.freebsd.org/.  Something we have wanted to do for quite some 
time is hold documentation review events.

There is a barrier to entry for reviewers because our documentation is 
either in DocBook or mdoc.  Reading the source is non-trivial and 
distracts from editing the content, even if you are familiar with the 
markup language.  Reviewers currently have no easy way to annotate a 
rendered version.

Annotator can simplify this for us.  The plan is to take a single 
section of our HTML-rendered documents, like this example:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-wireless.html

The necessary Javascript inclusions and a header with user instructions 
will be added to a copy of that file, and it will be set up on a web 
server temporarily.  Then we have a limited-time event where we ask for 
user annotations.  At the end, editors go through the annotations and 
update the document.

I set up a simple test, which works for a single user and session but 
shows that user login and storage are needed.

What I'm looking for now is a complete, minimal example, preferably one 
that does not assume a web framework and uses local storage for the 
annotations.  The openshakespeare example looks like a start.  What is 
needed for a storage service on port 5000?

Thank you!