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:
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.
2 Comments On This Entry
Please log in above to add a comment or register for an account
Search My Blog
Coding Using NEON Technology
on Yesterday, 08:57 AM
on May 08 2013 06:15 PM
New Platform Bring-Up with ARM® Development Studio 5 (DS-5™)
on Apr 30 2013 09:55 AM
如何利用全志安卓4.0 HDMI Dongle进行ARM DS-5 Streamline性能分析
on Apr 26 2013 10:50 AM
DS-5 Streamline Performance Analyzer on Allwinner Android 4.0 HDMI Dongle
on Apr 25 2013 04:58 PM