ARM Community: Desperately Seeking Info - a Darwinian approach to technical documentation - ARM Community

As writers at ARM, we always ask ourselves one particular question when we start to create a new document for a product: “What level of knowledge do I assume the audience will have?” If we assume too little, we are in danger of producing a large document that contains superfluous information. If we assume that the audience knows too much, then we risk losing them after the first couple of pages.

Meanwhile, the audience for these documents is trying to find information. Just like the Madonna film, “Desperately Seeking Susan,” where Madonna’s character searches for her soul-sister, the audience is “desperately seeking information.” They are looking for that vital piece of information to reach the next step in their development project. Typically, readers will need to sift through reams and reams of known information in the hope that they may find what they need, or worse, they may become lost in a morass of unfamiliar concepts.

So, the biggest problem that writers face when producing any technical document is that they need to accommodate a diverse audience with varying degrees of knowledge and understanding. Ideally, the writer needs to structure the information in a document such that it is both readily accessible and appropriate to the specific and immediate needs of the target audience.

A possible solution to this problem is something called Darwin Information Typing Architecture or DITA, which defines a more naturalistic structure for writing and organizing information. For example, DITA proposes a modular architecture for information in a document. Rather than the traditional hierarchical and linear book structure of chapters and section headings, DITA organizes information into discrete “chunks” of information called topics. These topics are classified according to their purpose. Information outlining a procedure to follow is termed a Task topic. An account of a fundamental principle is termed a Concept topic. A description of a specific item is termed a Reference topic.

Splitting information into separate topics and types enables the writer to be far more specific about the subject matter. For example, they don’t have to complicate a Task topic by explaining a command’s function or its syntax within that specific task. This information can be provided separately in Reference and Concept topics.

There is a huge amount of information about DITA available on the web. Below are some useful links, and in later posts I will provide more information about the other benefits of DITA. But, it is worth remembering that at its heart, DITA is an attempt to improve how we capture and disseminate knowledge.

At ARM, we are embarking on switching our technical documentation to DITA. To get a flavor of a document that uses DITA-style topic-based writing, take a look at the ARM Compiler documentation on InfoCenter.

The document still reads like a typical technical document, but the content consists of short, specific topics with cross-references to other topics that are likely to satisfy the reader’s requirements.

Please take a look and provide any feedback that you may have. Our hope is that by applying the DITA model to ARM documentation, we can improve the structure of the information and take some of the “desperation” out of seeking information.

Follow these links for more information about DITA:

• http://dita.xml.org/...orld-march-2011
• http://www.xmlmind.c...DITA/index.html
• http://dita.xml.org/...xport/html/1229

Jim Fallon, Technical Publications, ARM, is based in Cambridge and has written many technical manuals for ARM. He has worked at ARM for over 5 years and is currently helping to update and maintain the ARM Compiler documentation suite. He is passionate about documentation and believes that good technical documentation can be viewed as the first line of support for a product. Prior to joining ARM, Jim worked for Conexant who designed ARM-based DSL modems.