From wikis to reports 5

In EU research projects [1], it is normal for a number of partners to collaborate to produce a report, a written document, complying with a predefined style template. Most of the sections will be assigned to different people to write and review, usually in parallel. In general, there are three methods of handling this:


deliverable example

An example Deliverable/report

  1. Word or LibreOffice files.
  2. Google Docs
  3. LaTex

The problem with 1 is that merging changes from multiple people is rather hard. People tend to work in isolation, and it is left to the editor to combine all the various documents into one coherent one which resolves all conflicting edits. A problem with 2 is that it requires all documents to be stored on a Google server. This is sometimes hard to justify within an enterprise, for privacy and commercial sensitivity reasons. Where is your document located? How many copies exist round the cloud?

A secondary issue, is that offline writing or editing requires exporting to one of the options in 1 above, and when online, cut paste the revised contents back into the google doc. LaTex is good at producing printed output, but rather hard to learn for a novice. Tools like LyX help, but every now and then you have to resort to using LaTex macros. A second point to note is Latex does not have HTML output, so online viewing is of the PDF variety, and no wiki markup supports it.

Surely there is a better way. Wiki’s a generally very good at collecting input, but generally, rather bad at producing quality PDF output. One of the more promising solutions is to use Asciidoc as the markup format. This allows marked up text to be converted to acceptable quality PDF. Unfortunately not all wiki’s support Asciidoc, however there is one exception Gollum. Gollum is the wiki engine used to support wiki’s on Github. It supports a variety of markup languages, and has a large user base.

However one of the limitations of the Asciidoc tool-chain is that it is rather intimidating to customise. Enter asciidoctor . This is ruby based, and adds some improvements to the tool chain, for example, allowing multiple authors for a document, and provides templates for further customisation. For example, adding a boilerplate copy-right notice, or ensuring the enterprises tag line, and address are added. The TSSG internal report generator is an example of the type of customisations possible. So this combines some of the advantages of all the tools.

1. Collaborative editing and collection of material (via gollum)

2. A format that allows HTML and PDF output (asciidoc)

3. A toolchain to generate PDFs that can be customised (asciidoctor, and asciidoctor-fopub)

This results nice looking, consistently styled documents. You can find an example PDF here [deliverable-example]. Perhaps this might be a third option to consider when tasked with consistent documentation.


[1] PRISTINE project, web page: