How many times have you looked at a software project and made a decision whether or not to use it based solely on the quality of the documentation? Writing documentation is one of the most difficult tasks on a project, keeping this documentation accurate can also be hugely time consuming. Here at the TSSG we have been looking at different ways to create and distribute written documentation.
Lightweight markup languages such as Asciidoc offer the means to make writing documentation as fast and easy as writing an email. Asciidoc enables the process of write once, use everywhere mentality. The Asciidoc2html-pdf toolchain is a wrapper for the Asciidoc tool, it is designed to produce styled PDF and HTML output with customisable headers and footers with an automatically generated table of contents which can be used as project deliverables, research notes and or technical documentation.
AsciiDoc can be easily translated in to many different formats including DocBook, HTML, LaTeX, PDF, EPUB and man pages. This process also encourages authors to write content in distinct blocks which could then be re-used in documentation, articles, web pages, man pages at a later stage, without the need to constantly cut and paste text from different locations. This also has the potential of keeping all written items on the project in synchronisation, in some ways thinking and building your documentation, similar to how developers would think and build libraries for their code.
Depending on the level of granularity you wish to aim for, chapters, sections and paragraphs can all be broken down into separate files and stitched together at document build time. This allows huge freedom in document design, and provides the means to reuse content in many areas of the same project.
To begin using the Asciidoc format and utilising the Asciidoc2html-pdf toolchain you’ll need to install it on your favourite OS (it works best on Linux, but has been possible to install on OSX and Windows through Cygwin). The toolchain has version 8.6.6 of the Asciidoc tool bundled with the system. To begin the installation check the code base out from the GIT repository here and refer to the readme document bundled with the code base as it contains information about installation and the system dependencies required to operate the toolchain. The latest code base requires Python, Java and Xsltproc to be available on the PATH.
This toolchain has been in production within the TSSG for the past year, our experience has shown that documentation developed using the toolchain can be most effective when hosted using a source control manager such as GIT or SVN. In order for someone to create their first document they must initially follow the projects repository branching model, for example creating a GIT feature branch to hold the new work. The asciirock gem which in its initial state allows only for a new document structure to be created at the specified path is bundled with the Asciidoc2html-pdf toolchain. The intention is to continue development on this gem to the point where it can replace the asciidoc2html-pdf toolchain outright, by employing the Ruby implementation of the Asciidoc processor Asciidoctor. The readme contains detailed information on how to create a new document with the required structure suitable for building using the toolchain, refer to it for more information.
The index asciidoc file in which all document are imported must contain the following header template at the top, it is this information which the toolchain uses to populate the front page whether PDF or HTML. Once more the readme gives more detailed information on this area.
:reporttype: HOWTO :reporttitle: Configuring a .netrc file for automatic user authentication with bitbucket.org :author: David Kirwan :email: firstname.lastname@example.org :group: Telecommunications Software and Systems Group (TSSG) :address: Waterford Institute of Technology, West Campus, Carriganore, Waterford, Ireland :revdate: August 10, 2013 :revnumber: 0.1 :docdate: August 10, 2013 :description: HOWTO configure the .netrc file to allow automatic user credentials authentication with https://bitbucket.org :legal: (C) Waterford Institute of Technology :encoding: iso-8859-1 :toc:
Finally there are two different options available such as the Apache Ant and the Ruby Rake build scripts each execute the Asciidoc2html-pdf toolchain and build the documents into either HTML or PDF outputs. Refer to the readme for information on how to execute either build system.
The system is still early in development and is available on github, feedback, improvements and pull requests are most welcome!