JoAnn Hackos is well known in the technical writing community and is a member of the DITA Technical Committee. Recently she wrote the article asking, Is DITA Going to Tip? which explores Darwin Information Typing Architecture (DITA) in the context of an idea that will become widely accepted and popular as Malcolm Gladwell’s book The Tipping Point describes. She spoke at the Central Texas DITA User Group meeting held at BMC Software on January 25, 2006. This post contains a summary and notes from her talk. Our technical editor, Kelly Holcomb, took better notes than me, so I’m borrowing heavily from her notes for this post. 🙂 Thanks Kelly!
Books
JoAnn’s entry point for talking about DITA and structured authoring was the transition from writing books to writing topics. She stressed the necessary paradigm shift for writers away from thinking about what they do as writing books to thinking about what they do as writing essential, correct, easily accessible, and easily digestible content that users need to perform their tasks, meet their goals, get their work done, and be home by 5 P.M. That’s everyone’s goal when using technology, hoping it will help you get something done faster to free up time for other things.
She leads us out of the book model by stressing that manuals are not books—users don’t “read” them from the first page to the last like we usually think of reading a book. They use manuals to look up necessary information. Users are not readers!
She talked about our manuals being an outgrowth from the publishing industry, and of the excitement in the profession, years ago, of being able to produce information that was actually attractive. But the influence of desktop publishing has been detrimental because we have gotten so caught up in how the information looks (formatting, sticking to a “book” structure, marrying format to function) that we tend to overlook the real needs to the users. And, all the attention to formatting detracts from what we actually do as technical communicators (the perception of outsiders of what we do has been adversely affected).
She actually held up the “About this book” type of section as an example of an artifact of publishing with no real use for our users.
So, what do customers require? Tell me if you agree, and I agree with her list:
- Task-oriented information for getting things done
- Minimalism: less info=no glut
- No out-of-date information stuck in books
- Information that is easier to find and easier to use
Topics and DITA
What are topics?
- Discrete units of information covering a specific subject with a specific intent
- Small enough to promote reuse across multiple contexts and output media
- Large enough to be easily authored and large enough to be readable and coherent
- Able to be organized into a wide variety of structure, from linear to networked
Topics allow us to provide “just enough” information to the users. Writing topics removes the interconnectedness of books and lets information stand alone. Context is not provided by a super-structure (the linear structure of the “book”), but from within the topic itself by its complete, discrete information and links to related information.
DITA supports topics through its model of concept, task, and reference topics.
Specializations in DITA help the designers communicate with the authors about what kind of information they are writing.
With DITA, writers create maps. “Maps” are what our users need—a way to get into and through the information. She talked about getting away from the straightjacket of the PDF into an information-centric web site (her vision). Such a web site allows the users to find the information they need, and find other related information. She stressed the relationships of topics: providing access to related information or prerequisite information, and letting users give feedback about what other information might be relevant to a particular topic (suggesting other related info links). She also talked about unnecessary concepts: if you can’t relate a concept to a task that the user must perform, you should question the appropriateness and relevance of providing the concept in the documentation.
Planning topics
She stressed the idea that effective topic-oriented writing requires planning and collaboration, especially if information will be produced by many writers. The lack of collaboration has traditionally led to duplication of information, as well as gaps of information, in books.
- Begin with tasks that users must perform to reach their goals
- Consider possible scenarios that illustrate typical user tasks in the context of real-life goals
- Turn basic tasks into introductory tutorials
She used the AutoCAD documentation as a good example of providing brief tutorials for basic tasks (as AutoCAD users said, “teach us something in 10 minutes”). Then, she showed us how they augment the tasks/tutorials with conceptual information, often provided as videos. Then they add the reference information that is needed to support goals (their online reference command). This online Help/document provided three tabs at the top of the right-hand pane (the information pane). These tabs provide access to tasks, concepts, and reference information related to the current information.
Business case for topics
- Topics promote minimalist agenda—fewer words to manage
- Topics promote structured, consistent writing
- Topics are easier to localize, further reducing costs
- Topics enable multiple deliverables to meet the needs of diverse user communities
Manuals are tools that must be fitted to use; topics make manuals economically possible. Her story illustrating this point tells of a telephone repair technician who had to take not one but three snowmobile trips in order to repair a remote station. He didn’t lug a 500-page manual with him, as you can imagine.
Guidelines for topic-oriented writing
- Focus on best practices in information design (as always)
- Don’t construct elements for every bad design decision. In other words, don’t change the standards to fit your current content, but rather make your content conform to the standards
- Develop authoring standards and guidelines, and provide example for writers
- Demonstrate how to apply DITA elements correctly. Part of the editing process needs to look at the tags to ensure that they are used correctly. Incorrect use of tags will make reuse impossible.
- TRANSFORM information, don’t convert it!
- Use the transformation to harmonize topics and identify levels of reuse.
Information that came up in relation to questions asked by audience
I asked a question about the approach to implementing structured authoring, specifically analyzing content and creating models/specializations from that versus transforming information to fit in the standards and model. JoAnn’s advice: Look for the DNA of the information, the underlying structure that governs the information. Don’t try to squeeze every idiosyncrasy and every construction error ever made into the new model (transform, don’t convert).
Another audience member asked about the relationship between information mapping and DITA. They have practically identical philosophies; information mapping provides more types of information than DITA (7 versus 3), and information mapping has more to say about how information is developed, but in JoAnn’s opinion, the two methods are highly compatible. (She mentioned that the Information Mapping organization has just announced their support of DITA.)
Don Day or JoAnn also mentioned Michael Priestley’s article about scenario-based writing, which sounded interesting (illustrating a different way of approaching the content). Here’s a link to the presentation slides and article on xml.coverpages.org (Thanks, Don!) or if you’re an ACM member, here’s a link to a PDF download. http://portal.acm.org/citation.cfm?doid=944879.
Later, in a separate discussion, Kelly and I talked with Don Day about how the needs (habits) of mainframe users are unique: they love their books and have special rooms dedicated to documentation. IBM should know about those users! So, the delivery of the information is still traditional for mainframe products.
Feel free to comment on your thoughts on the meeting or the ideas presented here. I’m definitely interested in how you read manuals (or don’t read them).