In September, a group of us got together to write a book on Responsible Data in international development. As we’ve written about already, it was a great experience, and we’re pretty proud with the product too – a collaboratively written book, from start to finish (including design!) – in 5 days. But, as we’ve noticed in the last few months, few people among our desired target audience have enough time to read an entire book, and – perhaps more importantly – we want the book to be the start of a conversation with a broader group of people, too.

So, the engine room asked me to take a look at how the book could be put online, to facilitate this conversation online, and try to make the book a little more engaging for people we’d love to learn from and hear from. This blog post is a summary of what we learned along the way.

For reference: the book is 31,471 words long, including a reasonably long ‘further resources’ sections, and thanks to the PubSweet platform that we wrote it on, we have it available in PDF, OpenOffice, .doc, and raw html.

What do we want to be able to do?

To provide background to the initial scoping, here are three user stories I had in mind while looking at the various options:

1. As an engaged reader of the book, I want to comment on a certain sentence or section, so that I can discuss certain sections of the book with others with similar interests.
2. As an advocate for responsible data in my organisation, I want to link to/send certain sections of the book to others in my organisation, so that they can read just the section that is most relevant to them. I also want to be able to download certain sections of the book so that we can use them offline, too.
3. As an engaged member of the responsible development data community, I want to edit/adapt sections of the book based on people’s feedback, so that the book is a living, updated source of knowledge.

Platform final recommendation: Hypothesis

I recommended that the engine room use Hypothesis, built on Annotator.js, and running this on a static Github Pages site. Benefits of this platform:

• The text itself (via the site) would be hosted on Github, a reliable service, with a strong community already present, and with lots of functionality around exporting it in different formats, editing it easily and by various people, accessing it in raw formats, and with version control.
• The appearance of the site is very easily customisable, and lots of good looking templates are available already.
• There is a cost free option!
• Different chapter headings could easily have different slugs on the site, and having the actual text available on Github would provide alternatives for community interaction.

This would then have two options for community interaction:

1. The ‘low tech skills’ option: using the built in annotation tools in the browser to comment, annotate, have conversations. (satisfying user story 1), and simply linking to relevant sections via the chapter heading slugs (satisfying user story 2).
2. The ‘higher tech skills’ option: submitting pull requests and edits via Github, which also provides version control, forking and remixing totally new versions of the content with a low barrier to entry. (satisfying user story 3)

I would also recommend splitting the book into PDF chapters, and having a downloadable PDF per chapter linked to from the relevant section of the site. We’ve put the book on this platform, so you can see for yourself what this looks like in action!

Note: Genius seems to also do a lot of what we’re looking for, but from first exploration it doesn’t seem to offer tools for others to use to annotate on their own sites. One to watch for the future, though!

The 6 platforms I explored

Considering our main need – wanting to annotate online – there are is quite a selection of platforms out there already. For reference, here are a few others that I found, and the reasoning behind not choosing them. Note: if there are any errors in the summaries below, please drop me an email and we’ll correct them!

1. Digress.it

Note: currently on ‘hiatus’.

Digress.it is a WordPress plugin that offers paragraph-level commenting in the margins of a text. Digress.it is geared toward in-depth discussions of longer documents: article, essay or even book-length. Comments are attached to separate paragraphs.

Implementation options:

1. As a WordPress plugin on an already set up WordPress site
2. Sign up for a ready made site on digress.it

Advantages:

• Works across various WordPress sitefarms, so different document sites could be set up if needed.
• Open source

Disadvantages:

• If looking for a custom domain and hosting, $5 per month to cover basic hosting costs
• Can’t find any active instances where the plugin seems to be used: lots of examples have now ended, which suggests it’s perhaps no longer maintained.
• Link to register for a new account brings up a 404, and the last post on the mailing list was in 2013.

Conclusion: No go – seems to be no longer maintained nor working on any sites that I could find: because of this, ruling it out.

2. Document Cloud

DocumentCloud is a tool for organizing and working with large documents and document collections, a document viewer that makes it easier for reporters to share source material with readers and a publicly accessible repository of primary source documents that were used in journalists’ investigations. It includes automatic entity analysis through Open Calais.

Advantages:

• Every note has a unique URL, so you can point readers right to the passage you want to highlight.
• Annotations can remain public or private.
• Documents can be embedded within other websites

Disadvantages:

• Annotations can be made, seemingly, only by the user uploading the document and members of their team.
• Very focused on the use case of an investigative journalist; much less so on our use case.

Conclusion: No go – annotations can’t be made by anyone but the user uploading the document/members of their team, meaning that no conversations/feedback can be drawn from the community.

3. Co-ment

Co-ment® is the reference Web service for submitting texts to comments and annotations. Co-ment is an open Web service powered by free software licensed under the GNU Affero GPL license.

Advantages:

• Use cases given sound similar to our needs: being able to Annotate, Discuss, and re-write
• Exports to various (printable)formats
• Allows for annotations, responses to those annotations or comments, and ‘like’ or ‘plus ones’ by other users.
• Annotations can be nested, and users can be notified when someone responds to their particular annotation
• Allows version management, and comparison between different versions
• Has different user rights control: good for creating a specific working group around the text (observer, commentator, moderator, editor or manager)
• Provides analytics on number of comments, users, etc, as a standard part of the dashboard. (also could be considered as a disadvantage!)
• Each comment has a distinct URL.

Disadvantages:

• Name and email address of person doing the annotating seems to be ‘required’
• Text would be hosted by them (ie. the book would be imported into their system, and the site hosted on a domain owned by them)
• Costs:
  • 12 months (365 days) 84 €
  • 1 month (31 days) 10 €

Conclusion: Looks pretty good in terms of features – test case up here. Only concern would be around actually hosting the text with them (though it can be exported) – and also the visual appearance, the design doesn’t look great and seems to have limited options for customisation. Examples: the GPL v3 was written together with comments and annotations from the community. More documentation on using it is here, from that community.

4. Comment Press

CommentPress is an open source theme and plugin for the WordPress blogging engine that allows readers to comment paragraph-by-paragraph, line-by-line or block-by-block in the margins of a text.

Advantages:

• Allows threaded conversations
• Conversations appear in the margins, not above or below the main text (easier to read)

Disadvantages:

• Comment by paragraph rather than by selection
• No URLs given for specific highlights
• Fairly restrictive on structure of text-  needs to fit into assigned ‘CommentPress’ structure as the plugin has been restructured into a CommentPress Core blog theme.

Conclusion: No go – too restrictive on text structure, having to use the CommentPress WordPress theme, doesn’t seem very widely used.

5. HyLighter

HyLighter is built for intensive collaboration with virtually any size group on a single document or a large collection of related documents including Office files, PDFs, images, and other file types.

Advantage: Has an unusual (potentially confusing, potentially useful) colour-coded system for highlights

Disadvantage: Confusing sales pitch – unclear what they offer

Conclusion: No go – seems to be about collaboration on offline document formats, rather than an in-browser solution, and prices are vague (potentially expensive)

6. Hypothesis / Annotator

Annotator.js is an open-source JavaScript library to easily add annotation functionality to any webpage. Annotations can have comments, tags, links, users, and more. Hypothesis is built on Annotator.js.

Advantages:

• Annotations can have tags
• Annotations can be private or public, editable/viewable to different people
• Simple/lightweight to add to a website (couple of lines of script)
• Actively maintained (and we/I know the maintainers pretty well!) – and actively used
• Annotations can also be added to images (not just text)
• Can also be used to annotate local + web based PDFs (as well as websites)
• Can have threaded conversations, and be notified when people reply
• Lots of plugins for extra functionality (though unsure how maintained/good these all are!)
• Can host the text on a site ourselves, and simply add Annotator to it.

Disadvantages:

• The book would need to be set up on a website first – so extra tech skills needed.
• Setting up Hypothesis also seems to require a higher level of tech knowledge than the other options listed above.

Conclusion: Seems really good for this use-case; lots of functionality, nice and lightweight, looks good. We might need a plugin or two to make it do exactly what we want (eg. having URLs per annotation) – and it would require someone with a little bit of technical knowledge to be able to set the site up and add the script. Also has the benefit that we could style the site as we like.