Education Days 2010

It’s nearly impossible to explain two days of workshops in less than a thousand words; you just had to be there! As a result, I decided that this article will contain the main points that I took away from the workshops. If the other attendees noticed different things, I hope they’ll add their comments to this blog.

Topic-Based and Structured Authoring – Neil Perlin

We learned to write in topics instead of documents. A topic is a self-contained piece of information about a subject. If it is self-contained, it can be re-used or put in a different order. It encourages minimalistic writing, forces writers to organize their writing, and allows many different writers to contribute to a “document” without overwriting each others’ work. If your target documentation format uses an online help paradigm instead of a book paradigm, it’s much easier to think and write in topics.

We learned to develop a structure and use it consistently. Structure provides standard sectional, syntactic and stylistic rules. The structure can be unenforced and simply defined in a template or style guide, or you can enforce structure using various tools such as XML (eXtensible Markup Language).

We learned how to plan and manage the project of implementing topic-based writing and structured authoring, such as becoming aware of the company’s goals and promoting how this project can contribute to those goals. Neil was especially helpful with tips on dealing with the political situations that can develop between departments when implementing such a project.

We learned that the answer to all questions begins with “It depends…”

As he taught, Neil illustrated his points with stories from his extensive consulting experience. For example, sometimes he recommended the same conclusions that the employees reached, but since he’s a consultant, management listened to him. If you’re having trouble convincing management to do something, a consultant can be helpful in this regard. Sometimes he’s called in to review two competing proposals and choose one. If you’re looking for the best way forward, a consultant can provide an objective, knowledgeable opinion, but you don’t have to hire a consultant to do all the work.

In the afternoon, we did some hands-on exercises with our own work samples. We practiced looking at common elements, identifying the topic type, and creating an appropriate structure that would encompass all instances of this topic type. It was an interesting exercise to apply all the theories from the morning to actual documents.

After all Neil’s hard work, we took him out for dinner at Hog Tails BarBQue to satisfy Neil’s other professional interest…. See Neil’s blog for a restaurant review. You’ll have to scroll down to find Hog Tails.

DITA from legacy to the future – Bernard Aschwanden

Building on Neil’s information about topic-based authoring and structured writing, Bernard taught us about DITA (Darwin Information Typing Architecture). DITA is a standardized XML (eXtensible Markup Language), so it enforces structure and uses the topic paradigm. Since DITA is a standard, all the tools that support DITA can exchange information seamlessly. At the end of the hands-on section, Bernard proved this to us by taking topics we wrote in FrameMaker or XMetal, and opened all of them in both tools.

In a nutshell:

·         Information is written in topics, and the topics fall into three basic categories: task, concept and reference.

o        Task is a procedure; how to do something

o        Concept is what something is, and why it’s useful.

o        Reference is quick access to detailed facts when the user already knows how and why.

·         A map defines the organization and hierarchy of the topics. It creates relationships between them.

·         A reltable is another organizational component of DITA that allows you to create cross-references between topics that don’t depend on hierarchy. Gathering cross-references in a single entity allows you to manage these links separately from the information.

·         Special elements for content re-use and publishing:

·         A conref for shared topics; the topic in its entirety appears wherever the conref is.

·         A ditaval for conditional text; allows you to filter the information on an attribute so that only some information appears in the publication.

Besides learning about the components and composition of DITA, we learned how to convert legacy documentation to DITA. We heard about the cost, procedures for reviewing existing documentation, a conversion plan, mapping existing documentation to the DITA paradigm, and available tools. Since the information that is written in DITA is independent of formatting, you define the format using whichever scheme or tool you choose. For instance, you might choose a Cascading Style Sheet (CSS) if your output is HTML, or FrameMaker if your output is PDF.

Armed with basic information about the most commonly used DITA elements, we wrote a topic in either FrameMaker 9 or XMetal 6. Besides putting the DITA information into practice, most of us had the opportunity to try out a new tool or a new version. I found that writing to comply with the DITA structure requires a different way of thinking because each unit of information is compartmentalized into a predefined bucket. You begin by deciding whether you are writing a concept, task or reference concept; the order and structure of the rest of your writing is then determined by that decision. This is the nature of adhering to a standard, which brings about the benefits of content re-use and tool independence.

DITA is a large and comprehensive standard. Bernard did an excellent job of providing us with the maximum information possible in a short amount of time. The hands-on exercises helped us to grasp the concepts and put them into practice, and gave us a taste of the challenges involved. The final demonstration where he took the topics we all wrote and displayed them in two different proprietary tools, with no conversion or reformatting, showed us some of the possible benefits if we were to take on the challenge of using DITA. Love it or hate it, DITA is a fascinating construct.

Education Days 2011

If you feel like you missed something, you did! Hope you can join us next year.

We’re already thinking about Education Days 2011 and we’re open to suggestions. Please get in touch with Tracey Aitcheson  if you have a topic or a speaker who you’d like to hear.