---
title: asciidoc experiments
url: https://www.grahambrooks.com/post/2011-06-26-asciidoc-experiments/
date: 2011-06-26T00:00:00+00:00
author: Graham Brooks
tags:
- developer-tools
- Agile
- Writing
---

# asciidoc experiments

I have always been interested in text processing systems. This is
probably rooted in the time that I discovered computing and
programming. At that time the state of the art was ROFF (T)ROFF and a
whole family of plain text processing engines that produced nicely
formatted output.

With the advent of word processing applications the emphasis moved
away from plain test precessing systems to more sophisticated systems
involving opaque binary formats. More recently the use of binary
formats has fallen out of favor and many word processing systems now
provide a level of interoperability with other systems though more open
document formats.

A notable exception has been in the evolving popularity of Wiki -
online collaborative web sites where the content is entered in plain
text with formatting instructions included in the text. Over time
these formats have evolved into a sophisticated mark up language in
their own right.

Plain text mark-up makes it very easy to compare two versions or
variants of a document. At [GitHub](https://github.com/) the
[Gollum](https://github.com/github/gollum) system is entirely based on
controlling content using [Git](http://git-scm.com/).

One of the things I find challenging about word processing systems is
their lack of features that allow for collaborative writing. Many
documents these days are produced by a team of people and in these
situations editing a document means someone driving the process,
distributing updated version of the document and incorporating changes
into a master copy. Often these documents are distributed by email and
the filename used to distinguish versions. This approach means that a
lot of time is spent updating and merging.


[Git Scribe](https://rubygems.org/gems/git-scribe) takes a different
view. It uses [asciidoc](http://www.methods.co.nz/asciidoc/) formatted
text in one or more source files and produces documents in various
formats using different back-end processors. In this approach the
document source (plain) text can be managed using version control more
easily. Changes can be merged together easily. What you lack in fine
grained formatting control you gain in improved collaborative document
development and more optimal work-flow.