Category Archives: 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 the Gollum system is entirely based on controlling content using Git.

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 takes a different view. It uses 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.

Share

Five Ws sitting on a bench

Over the past year I have been involved in preparing quite a few documents, proposals, presentations etc. I have also been asked to review quite a few of these documents. As an author or reviewer I like test what I am working on against 5 Ws and one H to see if the important aspects have been covered. The Wikipedia article provides a good background and history, including the 1902 reference to Just So Stories.

It’s not that every document or presentation needs to answer each of these questions but that it should be a conscious choice not to include something.

A proposal/presentation view of the 5 Ws + 1 H

– who is using the system and/or who is the proposal for

  • Who
    • Who is the document for
    • Who is going to use the system
  • What
    • What is to be achieved
    • What is the system required to do
  • When
    • When is the solution required
  • Where
    • Where is the system to be used or deployed
  • Why
    • Why is the new system required
  • How
    • How is the system to be developed
Share

Prag Pro Wri Mo

I am going to take part in Prag Pro Wri Mo to find out if I have the inclination and capacity to write or if I am one of those people who would have liked to have written a book.

This initiative seems like a really fun and challenging idea and I am looking forward to getting started.

Share