Writing

Posts and articles that relate to the art and science of writing

The Elf Project

One fine day, Peter and I were discussing that we need an easy way to design a document before we actually start writing. Then we ran into trouble explaining it to folks. So we decided to build something; it’s way easier to explain if you can actually show it working. If you’d like to see and try it out head over to The Elf Project.

If you like to know the details, read on below:

The boring details

The system provides an intuitive top-down information design approach, and enables multiple stakeholders to collaboratively create actionable specifications for content deliverables. This system abstracts the authoring complexities and enables users with varying experience levels to collaborate effectively using this cloud-based service. Once the information design is frozen, the system uses open standards to communicate the design to the document authoring software to automatically create the skeleton documents.

Problem

Any reasonably complex content deliverable needs information design. Often, the folks who understand the information design the best are not the ones who implement the design.

Authors and stakeholders create a content outline or content specifications. After multiple iterations, a stable specification emerges. The current content creation workflow starts with tools such as Word and Excel. Authors then use the specifications to create content deliverables.

For example, in a Technical Authoring workflow, product managers and SMEs work with technical writers to create a document outline.  The technical writers then use an authoring tool to create the files and add content to the documents. This approach is manual, error-prone, inefficient, and most importantly not integrated with the authoring software.

Solution

The proposed solution implements a top-down approach to document creation, where a content outline is created outside the authoring tool. A connector for the content creation software, automates the tasks of document creation as per the specifications.

elf-workflow

 

The solution consists of the following basic parts:

  • Cloud-based front end that lets users design information outlines
  • Connector for authoring application that automates document creation

Frontend

The solution provides a web-based interface for users to collaboratively design a document outline. The website allows users to create an information outline, work with multiple stakeholders to review and finalize the information outline. The web interface used standard HTML5 and JQuery . Users can add/remove/rearrange chapters, titles, content using natural gestures such as drag and drop, copy and paste etc.

elf-project

Connectors

Connectors are used to translate the information outline into actionable automated tasks. In the current prototype, we use ExtendScript as a connector, which when run in Framemaker creates a book and document files, and adds information to the Framemaker documents.

Prototype

Try out a quick and dirty prototype to see the idea in action. It is currently prototyped for Adobe Framemaker. It is available at http://vikrantrai.com/elf.  You’ll need Framemaker 10 or later to try out the entire workflow. If you don’t have Framemaker, you can always get a trial version from the Adobe website.

 

BBC News Style Guide

BBC News Style guide is one of the best styleguides I’ve ever seen. It’s almost fun!

Why does the BBC need a styleguide? For the same reasons Technical Writers need them. The domain might be different, but the aim is the same.

One should not aim at being possible to understand but impossible to misunderstand – Quintilian

Download the PDF here.

Appended on 10th March 2010

Listing some more styleguides here.

If you know some good styleguides, and would like to share it with the world, post a link in the comments, and I’ll add then to the main list.

Computer software and hardware
Journals and Publications