I have used a wiki as my primary format for documentation for the past year and a half. I tried to corral a group of volunteer technical writers to edit and update the wiki, because I embraced the idea that collective intelligence beats the individual thinker in the long run. But even the most advanced wikis don’t have a structured authoring backend. With wikis, you compromise single sourcing, content re-use, and multi-channel publishing. So you really can’t move in both directions well. I feel like I’ve had to choose whether I’ll pursue structured authoring or social media formats for my help content.

While at the STC Summit, I kept thinking about metadata and the idea of sorting content semantically by queries that leverage the metadata. I asked more than a dozen of the smartest people in tech comm about this, and I came to the conclusion that if I ever wanted to do it, I’d need to embrace an XML format and develop custom semantic tags.

One evening I had a dinner conversation with Sarah O’Keefe about moving to XML. Sarah explained different ways to write XML and how to query the XML even when it’s not structured as it should be. She grabbed a napkin and drew the following:

The code Sarah drew for me on a napkin.

Yes, I kept this napkin! It was the best souvenir from the STC Summit. It’s funny because when she asked for an example of one of the metadata values and properties I wanted to use, I said role as the value, with editor as the property. But I must have mumbled it, because she wrote “elder” as the property instead.

After the conference ended and I returned to work, I decided to abandon my wiki and move all my content into our Mark Logic database, which stores content in XML. This is LDS.org’s backend anyway.  To do this, I would need to convert all my wiki topics into XML and add the appropriate metadata to run all the custom queries and provide the faceted filtering I wanted.

I spent several weeks coming up with the right metadata and applying it to all my topics. I was basically saying goodbye to Mediawiki and the idea of collaboration. I would structure my content in XML, and I would be the sole author. Not that many community volunteers edited the wiki anyway, but there was always the possibility that some day it might take off. Still, I had given the wiki almost 2 years without seeing fruit. It was time to try something else.

When it finally came down to the time when I needed to convert my content, I learned that the web development team had created special help templates for me. These templates included a WYSIWYG editor where I would basically create pages. Further, I wouldn’t even be the one converting the content. A special web development team would handle it all, populating the templates and creating pages, and even if I wanted to touch the content I could not. They planned to pull it directly from the wiki.

What about all of those metadata fields that I had labored over? I had to pitch the whole idea about semantic structure and findability again. In the end, they penciled in a future task in a later sprint to expose certain metadata fields in the templates for the web publishing team to use. The custom queries will be a future request, once my content is in XML.

I thought I would be swimming in XML and coding until my eyes turned blue, but it turns out that this approach is even less techie than the wiki. For the time being, I relinquished my publishing control.

I’m eager to see if the new format yields higher visibility and findability for the help. It probably won’t be until the end of summer when I can evaluate whether the migration from wiki to XML was a good idea.

In the meantime, I have not altogether abandoned the idea of collaboration. I’m a project lead for a community LDSTech project that is more community-sourced than my wiki ever was. I have more than a handful of writers creating and submitting articles.

But hoping someone will land on a help page, realize its a wiki, log in and make intelligent updates is a dream that only few groups have ever achieved (most visibly, Wikipedia). The promises and potential of structured authoring, with faceted filtering, semantic structures, and intelligent queries, seems to outweigh the attempt to collaborate efforts across large groups using wikis.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

So many different ways to go.

It’s been a couple of weeks since I posted about my team’s search for an enterprise authoring strategy. So far, we’re just as split as ever about the problem. It seems that you can go four separate routes: DITA, HAT, Web, or Wiki. Here are some of the paths and difficulties we’re encountering.

DITA

DITA has traction as a new standard format for help authoring, but the DITA Open Toolkit output isn’t attractive out of the box. Further, the HTML output is a far cry from the tripane help output, which we’re accustomed to seeing from traditional help authoring tools.

While DITA is a cool idea, relinquishing control over the way the help looks will hurt our chances of getting buy-in from other groups and will leave us powerless to meet the needs of project managers who ask for some customization beyond margin adjustments and typography.

Scriptorium has a DITA PDF and tripane help plugin, which looks promising (see A makeover for the DITA OT’s PDF plugin). I caught a glimpse of it in the Attractive DITA webinar. Scriptorium is up front about pricing — $10k for the PDF plugin, $4K for the tripane help plugin.

Although I like the idea of the DITA standard, I dislike the idea that I would need to be a programmer to control the output. That puts our team in a position of vulnerability that none of us wants to accept. About the only solution in the short term is to hire a consultant to make the help look decent, and then just leave it be. Leaving the output fixed does score a point for consistency, but my team is design savvy and used to being in control.

HAT

Another path might be the help authoring tool (HAT) route, using tools such as Flare, RoboHelp, or Author-it. Flare has just released version 7, which allows collaboration through SharePoint as a file repository. This would be great, since we have a heavy SharePoint environment at my work. Author-it, another strong HAT, has a mind-blowing plugin called Author-it Live that allows a logged-in user to edit the online help inline similar to a wiki.

HATs are compelling because they seem to offer a complete solution with granular control over the output. The only problem is that each author usually needs an instance of the HAT, which is about $1,000 each depending on the tool. The Author-it Live solution allows concurrent licenses to the product, so the users don’t need to be dedicated — just limited to a certain amount of users at a time.

Author-it is attractive because another group in our organization already purchased this solution (but hasn’t implemented it yet). Also, the tool is robust, which is something we welcome. But trying to force the tool on others in surrounding departments who may not be technical or open to change will be an uphill battle. It’s hard to go to other groups and say, Here, buy our tool, learn our ways, use our output profiles when they already have a simpler solution that seems to work for them.

Web

Neither DITA nor HATs provide a Web 2.0 output. We’re all conscious of the fact that tripane help is a relic of 1995, and invites as much confidence in users as a station wagon. While Sarah O’Keefe suggests that actual user standards for document design are probably below our own — that is, users are more interested in the content, not so much in how it all looks — we want our help to fit in line with the current century.

Many web content management systems, such as Drupal or WordPress, provide an abundance of web elements that speak the same language as contemporary Internet users. Categories, tags, comments, RSS feeds, most popular posts, multimedia, jQuery — it’s all available in one experience in a website format.

The problem with these web CMS formats, though, is that you sacrifice content re-use and printed output. At most, a topic on a web page may be printable by itself. Web developers don’t care about re-use, so this is not a feature you’ll find.

We were excited to see that EasyDITA exports to WordPress, even though such an export from DITA is already available through a free plugin. Unfortunately many organizations, including our own, don’t support MySQL / PHP solutions. And even if they did, we’re skeptical that a WordPress theme could offer a navigation-friendly table of contents for hundreds of topics. And once you output to WordPress, there’s no round-tripping back into EasyDITA.

Some developers in our organization actually built a WordPress-like CMS, which they use to run the Newsroom. Amazingly, it uses our Mark Logic XML database on the backend, so theoretically we could write some XQuery scripts to get the content re-use and printed output that we need. But none of us knows how to do this, and we’re not so excited to adopt an XML solution that doesn’t involve DITA.

Wiki

Wikis such as Confluence and Mediawiki have appeal because we do have a large volunteer community. We’re already using Mediawiki for these volunteers, and it seems to be working in some areas. For example, the LDSTech wiki has regular contributors, and FamilySearch apparently has 50,000 Mediawiki pages with genealogy content.

I love the ease of collaboration that wikis offer, but they do a poor job with traditional help authoring requirements, such as selective re-use, access control, multi-channel publishing, and so on. Wikis can be styled with a Web 2.0 look, but most wikis I see are sprawling atrocities with column widths spanning the entire length of the browser, and no attempt at a table of contents.

Also, it seems that I am the only person on my team even remotely interested in wikis. On top of all this, I struggle to make community efforts worthwhile. (See my post, Do Community Efforts Work?)

Wikis do have a strong pull, though, since our organization wants to move more toward community integration in the future, with goals as ambitious as having 80 percent of the work done by volunteers.

Future Requirements

The most troubling problem in our enterprise strategy is that we’re pursuing a solution based on hypothetical requirements. There isn’t currently an enterprise-wide authoring practice, so finding a tool that is easy to use, collaborative, standards-based, cost-effective, and has attractive PDF and web output is based on the idea that people in various departments will actually adopt our solution and fall into line with the new methodology.

Our next big question is this: Once we select/compromise on a tool, how do we take it enterprise-wide? We don’t want to push the issue too early, or we’ll get every tribe vying for his or her own preference. If we get our own house in order and push our solution after figuring out what it is, we risk formalizing a solution that doesn’t meet their needs or wants of all the surrounding departments. We may end up with an approach that is designed for the enterprise but in reality is only used by us.

————-

photo by Christine Selek on Flickr

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

In researching this, I stumbled across a goldmine of an article on the History of DITA. The article (mostly by Bob Doyle) traces the evolution of structured authoring from its earliest attempts in the 1960s through the present day. The history seems to encapsulate all the major innovations of technical communication, culminating in the formulation of DITA.

According to this history, DITA can be traced from the following previous approaches and philosophies: Quick Reader Comprehension (QRC), Sequential Thematic Organization of Publications (STOP), Information Mapping, Minimalism, SGML, Docbook, and other innovations.

Tracing this evolution is fascinating. I’ve tried to read through some of the sources mentioned inasmuch as I could find them online. I’ll try to retell the history with my own commentary along the way. At the end, I’ll explain my own method for help authoring.

Quick Reader Comprehension (1961)

Around 1961, T.J. Matthews, an editor/publisher at the West Coast Navy Laboratory, developed a Quick Reader Comprehension method (QRC) for reports to increase reader comprehension while also making authoring more efficient. To increase the comprehension, he invented a format in which he labeled each section with the main idea on the left, while writing the details are on the right, as shown in the image below.

Signposts in the marginalia facilitate scanning and accommodate both novice and advanced users because all users need "the gist."

Matthews explains the philosophy behind this format:

The recipients of an R&D report often differ widely in their subject matter knowledge, use for the material, time for study, and desire for study. They do, however, all have one thing in common. They all need to grasp the main points of the presentation (3-4). … the headings and marginalia that the scanner sees do serve as signposts that direct him to complete text descriptions. This provides a sort of random access effect. The report holder has an intelligent basis for deciding whether to study or skip any part of the material. (Quick Reader Comprehension, p.5)

In other words, the marginalia serve the more advanced user who only wants to quickly scan the material. The novice user who needs more detail can easily dive into more depth by reading the text on the right. Matthews’ technique tries to solve the problem of delivering the right amount of information to the audience given the variety of user needs and backgrounds.

Matthews also places a heavy emphasis on illustrations. Illustrations can serve the same purpose as the marginalia, allowing the reader to quickly scan through the document, reading the illustration captions and looking at the visualization of the information to grasp the whole of it. This is actually how most people read National Geographic magazine.

Matthews argues that “literary” (or text-heavy) approaches to technical writing often result from students graduating from English departments, where there is a constant focus on texts rather than graphic design. Matthews’ monograph itself is illustrated with graphs and other visuals to depict his ideas. He notes that students who want to enter technical writing need a solid background in graphic design, because “Art and science are not two things; they are two sides of the same thing” (Thomas Huxley in Quick Reader Comprehension, p.12).

To decrease the authoring time, Matthews creates a modular authoring process in which each section is a standalone topic that can be prepared and finished independently. This allows the authors to work on any part of the document at one time rather than proceeding sequentially through the material. Matthews explains:

“…each section or subsection is confined to discussion of a single topic. There is no cross-referencing. This permits the sectional topics to be prepared at any appropriate time and in no particular order. They are done piecemeal. This approach has several advantages over more usual methods. First, outlining is greatly simplified and relegated to one of the last, rather than one of the first tasks in reporting. Second, if the units are prepared during the course of the technical work, then large blocks of material are ready for use as soon as the problem has been completed. It is only necessary to arrange these blocks in logical sequence and write transitional sentences or paragraphs. Third, the reader benefits because the author is obliged to stick solidly to one subject at a time.” (Quick Reader Comprehension, p.6)

In other words, Matthews is moving toward a modular writing process in which you have a series of independent, self-contained modules rather than one long text. This speeds up authoring time and also increases reader comprehension because each section will have a stronger focus. This facilitates the reader who skips certain sections of a document and reads only specific areas.

STOP Storyboarding (1965)

The next major development comes from a publications department at Hughes-Fullerton Aircrafts. Walter Starkley explains that “the notion was to construct the proposal entirely of two-page modules, with text and any associated visual facing each other” (STOP, p.42). In other words, Starkley’s STOP method is probably the first quick reference guide.

The following image shows the STOP format.

The STOP method has a graphic on the right and text on the left. Content cannot exceed these two facing pages, and you must always have a graphic, even if you're only visually depicting your argument.

Starkley says some writers objected, noting that some topics called for more elaboration beyond two pages, and other topics don’t have visual potential for the required graphic. To address this, Starkley says research shows most writers switch topics after about 500 words anyway (the length of text allowed on one STOP page). For the graphic, they allowed the graphic to visually depict the argument or ideas instead of showing some object.

Because you had to write for a specific structure, the STOP method is one of the first instances of structured writing. The content could not be longer than two pages. The left facing page had to contain explanatory text, while the right facing page always showed a graphic. This consistent structure no doubt led to a predictable pattern for readers to follow.

The writers pinned these guides up on the wall for readers to look at. Because each two page module was self contained, “the reader [was] confronted with a self-contained and easily assimilated theme wherever he may open the document” (STOP, p.47). Again, this self-containment of topics is another instance of modular writing.

Notice the STOP method’s emphasis on illustrations combined with text. This emphasis on illustrations will be mostly forgotten by the time DITA develops.

Information Mapping

Robert Horn builds on some of the previous concepts of labeling and modular writing, but he also introduces something new: information types. Horn identifies seven major information types:

Blocks in the domain of relatively stable subject matter can be sorted into seven basic classifications, which we call ‘information types.’ The seven information types are:

• Procedure
• Process
• Concept
• Structure
• Classification
• Principle
• Fact

(Structured Writing as a Paradigm)

Horn then analyzes the optimal structures for each information type and develops an approach for each type. Horn also introduces the idea of “information blocks,” which are similar to paragraphs but more tightly focused on a single idea, and usually about 7 sentences (no more than 9, to fit with Miller’s Law of 7 plus or minus 2). These information blocks chunk the information into reusable components for “precision modularity.”

The following is an example of a document structured with Information Mapping.

Information mapping classifies information into seven main types and then recommends an optimal structure for each type. In Information Mapping, information blocks are used instead of paragraphs. These blocks are short, contain no topic sentences, are labeled, and are modular.

Information Mapping is still a practiced method for authoring, and there’s even an Information Mapping conference in Texas this week. However, reading about Information Mapping is somewhat difficult because Horn has trademarked the technique and restricted access to the material. However, you can see a before-and-after demo here.

Minimalism

The next major development is a concept called minimalism, introduced by John Carroll in his book The Nurnberg Funnell. The basic ideas is that learning takes place through action and exploration, not through reading manuals. The more information you can remove from a manual, the quicker you can get users into the application, exploring and learning for themselves.

Carroll has four main principles in his minimalism approach:

• Choose an action-oriented approach.
• Anchor the tool in the task domain.
• Support error recognition and recovery.
• Support reading to do, study and locate.

(See Application of Theory: Minimalism and User Centered Design, by Mary Lou Mazzara.)

In other words, minimalism isn’t just about reducing word count because people are busy and don’t like to read. Minimalism is grounded in learning theory: users learn by doing, not by reading. Get the user acting in the application. Focus your topics on real tasks the user wants to do. When the user makes errors in the application, provide ways to guide and correct the user.

It seems at this point that graphics and illustrations are no longer emphasized, because the application itself is the visual illustration.

In Managing Your Documentation Projects, JoAnn Hackos relates a story that illustrates how too much information can “get in the way of learning”:

In one case study, a publications group decided as part of a paper reduction goal to reduce the size of their hardware installation manuals from over 100 pages of text and illustrations to approximately 20 pages. They eliminated redundancy and cut unnecessary information in the process, but they never consulted the users. All the decisions to eliminate information and redesign the installation books were made by the technical writers and the developers.

The users, 98 percent of whom were trained company techniques, were asked to review the content of the new, shorter manuals for accuracy. They carefully corrected errors in the existing text. Finally, they inquired why anyone in their group needed 20 pages of text to install the hardware. Once they were asked, the technicians explained that all they needed was a picture of the board to verify that they had the right piece of hardware. (103-104).

In other words, by becoming familiar with user’s needs, we can often reduce the information in our manuals significantly, not just from 100 pages to 20, but down to 1 or 2 pages.

DITA

In the interest of time, I’ll skip past SGML, Docbook and go right to the more well-known cousin/successor: DITA, or Darwin Information Typing Architecture. DITA builds on some of the developments of these previous structured authoring approaches. For example, DITA emphasizes modularity of topics, with the idea that each topic is a discrete, self-contained unit that the user can read without requiring a larger context.

DITA also identifies structures for different types of information, but rather than identifying seven types, it simplifies it to three: concept, task, and reference. Each topic can be one of these three information types. The topics are then assembled through maps that can contain any number of topics.

DITA is also heavily minimalistic. The task types, for example, require a structure that limits content to just one short paragraph after the title, and also eliminates stem sentences that introduce the procedure sequences. So far, not much new.

Where DITA is different is in the emphasis on content re-use and the separation of content from format. Why the emphasis on content re-use? In DITA 101, Ann Rockley explains:

One of the largest impacts of technology on information development is the addition of so many new formats for delivering information. No one just delivers a user guide (book) any more. There is an increasing need for information to be delivered in multiple formats. (DITA 101, 114)

In other words, content re-use is important today because we have more deliverables to produce. This is particularly true due to the Internet, which introduce a need for web help, and with mobile devices, which require a mobile format.

Another strength of DITA is that its structure enforces consistency, so for every task type, readers will become accustomed to the same format. This structure is enforced through the XML architecture of DITA, which requires certain tags in certain orders. More consistency leads to greater usability in the document.

Most importantly, DITA allows you to re-use or single source topics into different deliverables. For example, you can create a guide focused on a specific role, or for a specific scenario; you can compile a lengthy guide or a short guide. Because you can select and compile topics at will, you can create a variety of deliverables that better address a specific user level, context, and need. Ann Rockley notes that this selection allows you to get the right information to the right user at the right time (DITA 101).

DITA's chief strength is that it allows you to re-use content easily. You can create myriad guides with different selections and combinations of topics. This allows you to address a wider variety of users, roles, scenarios, and other contexts. You can get the right information to the user at the right time.

(Image from Reuse strategies and the mechanisms that support them, ditaxml.org)

Because content is separate from format, DITA requires a rendering component to transform the XML (your tagged content) into an output. This is part of the beauty of XML — you don’t hard-bake the format into the content. You can apply a completely different style to the content without actually changing the content. However, customizing the stylesheets requires XSLT programming knowledge, so this also potentially a drawback of DITA.

Beyond DITA

DITA is an impressive format, so one might ask, what could possibly come next? Is DITA the most cutting edge approach to documentation, the culmination of years of refinement and adjustment?

Noticeably absent in DITA’s functionality is a collaborative, wiki-like component for working with non-writers, such as stakeholders, project leads, and end-users. However, Don Day, chair of the OASIS DITA Technical Committee, is working on a project that will combine DITA with wiki-like functionality so that DITA can be used as a collaborative tool for a wider audience.

Other developers are working on exporting DITA to a wiki format, and then back again (round-tripping). Lombardi software has developed a method for the export of DITA to Confluence wiki. This looks promising if you use Confluence.

Only Half the Problem

I like the idea of DITA. It should be the back-end technology behind nearly every documentation tool. It clearly has the potential to make authoring processes more efficient. However, DITA only solves half of the problem. Remember back in 1961 when T.J. Matthews tried to solve the problems he was facing with his QRC method? Matthews starts his essay by complaining how the scientist today entering the space era “faces insuperable problems in attempting to keep himself informed on what he needs to know.”

He then asserts:

The Quick Reader Comprehension (QRC) method of R&D reporting promises to make both writing and reading more productive. It is potentially capable of saving at least half the manhours that scientists and engineers spend in manuscript preparation, and of increasing greatly the amount of information that can be obtained in a given amount of reading time. (Quick Reader Comprehension, p.3)

It's equally important to increase user understanding as it is to improve authoring efficiency.

Matthews’ attempt is not just to create a more efficient authoring process, but to improve the users’ learning, their rate of information absorption and comprehension. DITA just provides more of the same content in different combinations — topics in long guides, short guides, role-based guides, scenario-based guides, online help, mobile help, and other forms. The ability to pull together topics in the selections you want is critical and a huge step forward, but remember it’s still the same topic content. And of course that’s the idea of DITA — same content, but wrapped in different packaging.

However, as a total help solution, we have to keep in mind the other half of the problem: helping the user understand the massive amount of information we’re giving them. DITA should be a component within a larger learning strategy, not the solution for learning. Users who look at DITA as the magic button for perfect user assistance are missing a key point. DITA does not significantly enhance learning in itself — it’s just an authoring efficiency.

Multimodal Learning

The innovation in technical communication today needs to focus more on innovation in learning techniques, not just efficiencies in authoring. As we know, users interact with help material in a variety of contexts. Sometimes they read to learn, other times they read to do. Some users are novices who can barely double-click a mouse; others can understand the code running behind the application. Some users are voracious scanners who turn page after page looking for information; others are visual learners who need to see in order to understand. Others need someone to explain tasks to them in person; others prefer interface tips and notes and they explore on their own.

No help material will provide a one-size fits all solution. Rather than simply regenerating the same topics in different outputs, what users need for learning is a multimodal help experience. Just as conferences that offer nothing but lecture after lecture bore their attendees, help material must also provide content in different modes. Not just help in different formats, but different modes entirely. These different modes will not only suit different users but will also reinforce learning with different senses.

The four categories of multimodal learning that help content might address are as follows:

Video (screencasts). Probably the single greatest tool for learning a software application is to see how to do it. Our minds are visually mapped. When we watch how something is done, we understand. No amount of descriptive text and screenshots can really communicate all the a user takes in by watching a two minute video. Lynda.com, a video tutorial site for hundreds of software products, is the probably most popular example of technical communication on the web.

Illustrations (quick reference guides). A user looks at an overview of the system to gather a holistic idea of how it works. A two-page quick reference guide (QRG) with an illustration fills this need. You can’t just extract this content from a topic in your online help, because the content is integrated into the illustration, which may only be a screenshot with callouts on it, but ideally it’s more conceptual. In my experience, the content has to be revised for the illustration. To make an analogy, a quick reference guide is to a reference manual as a poem is to a novel. It’s not just the same content — it’s compressed, it’s an overview. It captures the whole in a visual way rather than explaining the parts.

Text (wiki or online help). The user who wants to read the details, or who needs a quick answer to a “how-do-I” question, can consult the written material to find the answer. A wiki is often the best solution here in collaborative environments, because it takes advantage of collective intelligence. But an online repository of any help content also works as long as it’s searchable. DITA can provide a good format for this content.

Action (practice and exercises). As John Carroll rightly pointed out in minimalism, you only truly learn something when you act, when you do. Users need practice problems and exercises and if possible, a test system, where they can experiment and explore the ideas and techniques they are learning about. These invitations to act can be added as “suggested homework” at the end of videos or put into a training workbook.

There are other modes for learning, of course. For example, teaching. When you teach a subject, you learn it better than anyone else. But how do you incorporate this learning mode except in a classroom setting? Perhaps if your online help is a wiki, you can give every user his or her own space where he or she can make notes on key tasks. Or encourage forum participation to teach others. But since there isn’t a practical application, I omitted it from my big four above.

The acronym for these four main modes of learning is VITA. In Latin, this means life, which is appropriate for the balance of the approach.

VITA is an acronym for video, illustration, text, and action. These four modes of learning provide the right balance to optimize user understanding.

These four modes aren’t just the same content pushed out into other formats. They are modes of learning. Some might criticize my approach to say that it falls under training or instructional design more than technical communication, but these lines have always been blurry. Our purpose as technical communicators is not merely to communicate information, but to help users understand the information and to become power users of the application or system we’re educating them about.

DITA could be used in this multimodal learning solution. DITA might be a wonderful tool for pushing topics out as screencast scripts and training material, but in my experience, the same topic doesn’t work without significant alteration. Single sourcing breaks down when you switch modes in drastic ways — going from text to illustration, or from written to spoken communication.

For me, it’s less important to try re-using content as it is to create content in new modes. And that’s the key deception of DITA. DITA would have you believe that you can single source your way into every possible deliverable. In reality, you’re just making potatoes in a few different ways (scalloped, mashed, boiled). You’re still giving the user potatoes. VITA is a multimodal approach, giving the user a full array of nutrition options, so to speak. It educates and informs by touching almost every sensory input.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Sarah defines authoring as “a publishing workflow that lets you define and automatically enforce consistent organization of information.” Typical structured authoring models include DITA, DocBook, S1000D, ATA, and SPL. Flare, Robohelp, wikis, and other help authoring tools and platforms that do not enforce a structure aren’t typically considered structured authoring.

If you’ve been following my blog for a while, you may remember my brief interview with Sarah from the 2009 STC Summit.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

In this podcast, I talk with Ricardo Amigo, a translator and podcaster in Mexico City and Costa Rica, about the field of technical writing. This podcast is more of a reverse interview. Instead of me asking the questions, Ricardo interviews me. The general topic is the field of technical writing, including all of the following:

• My path into technical writing
• Structured authoring
• XML and DITA
• Information architecture
• Usability — for documentation and software interfaces
• Publication formats for help material
• Breaking into technical writing
• Tools for help authoring
• The growth of technical writing
• Creativity and technical writing
• A typical day as a technical writer
• Translation techniques and tools
• Simplified technical English

Ricardo’s company is called Amigo Audio, and they principally do translation. For example, if you need your manual or software interface translated, Amigo Audio can help. You can contact Ricardo Amigo at sinpapel@yahoo.com. Additionally, you can read more about their translation services at Amigo Audio.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Scriptorium

Scriptorium has created a brief survey about structured authoring. The purpose of the survey is to gather “input from everyone: those who have implemented structured authoring, are planning to implement it, or have decided against it.”

The survey only took me about three minutes to complete. When the results are published, each participant receives a free copy (valued at $200).

Take the survey here.

You can read more details about the survey here.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

DITA (Darwin Information Typing Architecture) is an XML standard in technical communication

For a blog about the latest trends in technical communication, I’ve been conspicuously silent about DITA, the XML standard for technical documentation that is rapidly becoming the norm in the industry. Tonight I realized that I need to examine more closely where I stand on DITA. Several events prompted this.

At my work we have a small authoring group that is tool independent. I use Flare, another colleague uses RoboHelp, another colleague has no need for a robust help authoring tool, another department uses UPK (Oracle’s help authoring tool), and we don’t really have a unified approach. Adobe just released its new Technical Communication Suite that includes the latest version of a package of tools. Flare continues to move forward, as does Author-it and Doc-to-Help. But I’m feeling a bit fatigued by these proprietary tools. Rather than choosing another tool, I would rather choose a standard format and let individuals choose their own tools to create documentation in that format.

The WordPress Docs mailing has also been heating up. Apparently WordPress has come to the realization that its Codex, a giant wiki that would kill all trees in the world if printed, does not satisfy the beginner’s need for a basic “handbook.”

WordPress’ wiki has been, in my opinion, a fascinating project of community documentation. From what I understand, a previous wiki held WordPress documentation but was abandoned to create the Codex. Now the developers are considering transfering the core information from the Codex to a DocBook format, which they would maintain in a Subversion repository (SVN) so they can manage quality control and branching. If you want to see in to the heart of Web 2.0 and documentation, look closely at WordPress.  The Codex has grown beyond itself, become chaotic, redundant, outdated in parts, maze-like and unnavigable. Still, nuggets of essential information are spread throughout, making it indispensable. Maintained almost entirely by volunteers, the wiki proves to be a problematic format. It can’t sustain long-term, massive amounts of information before people feel the need to start fresh again.

According to the WordPress leaders, the wiki’s main problem is its inability to support branching. You can’t easily separate documentation for version 2.2 from 2.3 to 2.4, 2.5, 2.6, and 2.7. On the wiki, it’s all the same page.

Fed largely by user-generated content, wikis will inevitably contain stale information. For example, the long page I contributed to the WordPress Codex remains dated to version 2.5 or so, whenever I wrote it. (I’m not inspired to update it.) There’s no ability to impose quality control, to have a systemic way of sorting and verifying and organizing updates, changes, and other modifications.

Most importantly, though, the wiki doesn’t support flexibility of deliverables. There’s one product, one massive mountain of information. Each user has to make his or her own path through it. In all the documentation I’ve delivered, the long manual — the massive wad of information — has always been met with disgruntled looks and resistance. Users want condensed, short chunks of information specific to their role and situation. They want information without inundation. This brings me to DITA.

DITA provides the ability to chunk information, to deliver selected topics in a variety of compilations and output to various formats. It allows the passing back and forth of this content among authors regardless of tools.

My hesitation with DITA has only been that it’s too early to adopt. But I believe the turning point has come. There are, now, enough plugins, transforms, authoring editors, and other supporting technologies that writers can begin to use DITA successfully, without setting themselves too far back.

DITA has even made headway into WordPress. Mike Little says he has built “an importer which will take the XHTML generated by DITA and import it into WordPress as a
hierarchical set of pages.” He  “even have a version for WPMU [WordPress Multi-User Edition] that supports populating each mu blog with separate areas of content.”

I’ve kept my eye on DITA for the past two years, but I think it’s finally time, at least for me, to look more seriously into adopting and implementing it.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree