I'd Rather Be Writing » doc-to-help

Where I Stand on DITA

Tom Johnson — Sat, 24 Jan 2009 06:28:02 +0000

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

Top Technical Communication News for January 2009

Tom Johnson — Mon, 12 Jan 2009 05:29:44 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 12 min.

In this podcast, I cover the top 10 technical communication news items during the past month. This is a different type of podcast than I’ve normally done. The show notes below are excerpts of what I cover, but without any commentary.

1. Techcomm toolbox

One of the most common questions heard on many forums is “What tool do you use for [purpose]?” Answers vary, of course, because everyone has their own favorites and some folks will even answer that the right tool is “the one that best meets your needs”.

Sometimes, many people will answer that you need to look at the different tools, download trial versions, and test. But where is the list of tools to choose from?

It’s here at TechComm Toolbox, your online resource for all applications, services, consultantsm, and trainers related to technical communication.

2. Emergence of STC groups on twitter

More and more STC groups are joining and participating on Twitter: stcaccess, stcchicago, stchouston, stcboston, stcintermtn. Also, Writer River now has a Twitter feed: writerriver.

3. WritersUA Salary survey and tools survey going on

The WritersUA Tools Survey is underway. The survey is designed to provide our community with a guide to the relative popularity and satisfaction of a number of tools. … The Salary Survey provides a look at the various factors that contribute to higher salaries in the software user assistance community.

4. Jing Pro Released

Jing Pro brings you simply the best-in-class experience for quick visual online conversation. Imagine everything you already know and love about Jing, then add:

* HD quality video for the web
* Direct output to YouTube
* No more branding on the end of your videos.

5. I’m a tech writer photo gallery

Technical Writers (aka Technical Authors, Content Wranglers and Documentation Managers) have an unfair image. This project aims to challenge this image, by showing technical writers in a different light. The photos below are of technical communications professionals, doing a variety of activities.If you are involved in technical writing and you’d like to be included, contact us and send us a photo, together with your name and location.

6. STC to record and make available the entire Summit

Beginning this year at the Summit in Atlanta, STC will capture the content (audio and visuals) of almost every session and make it available to attendees at no additional cost. This will increase the value of your experience tenfold. After the conference, STC will sync the audio with the presentations and make them available (by passcode) for attendees on the STC website. This will allow [you] to “attend” all those sessions [you] missed. It will also allow [you] to revisit the ones that [you] did attend and to refresh [your] memory of the fine points made by the speakers. (From Mark Clifford’s January News and Notes)

7. WordPress 2.7 released.

This may be the last time you ever have to manually upgrade WordPress again. We heard how tired you were of doing upgrades for yourself and your friends, so now WordPress includes a built-in upgrade that will automatically notify you of new releases, and when you’re ready it will download them, install them, and upgrade your blog with a single click. [Also, BuddyPress is in beta: "BuddyPress is a set of WordPress MU specific plugins, each plugin adding a distinct new feature. BuddyPress contains all the features you’d expect from WordPress but aims to let members socially interact."]

8. Alltop publishes Tech Writing category

Alltop is an “online magazine rack” of popular topics. We update the stories every hour. Pick a topic by searching, news category, or name, and we’ll deliver it to you 24 x 7. All the topics, all the time.

9. Camtasia 6 released

When recording audio and video at the same time, it’s hard to be perfect. So we’ve made it easier to fix mistakes. Simply decouple the audio and video tracks to edit them independently. And move audio clips between (and along) tracks to line everything up perfectly. Bottom line: fewer retakes and less time spent on editing.

10. Doc to help releases 2009 version, with ribbon-based interface

What’s new: built-in xml based editor, dynamic help control for embedding help in .net applications. xhtml converter, drag and drop linking, and abbility to import project settings.

Blog Sponsors

Podcast: Help Authoring with Doc-To-Help 2009, Interview with Nicky Bleiel

Tom Johnson — Tue, 06 Jan 2009 05:28:40 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 35 min.

ComponentOne recently released Doc-To-Help 2009, which introduces a complete redesign of their user interface. In this podcast, I talk with Nicky Bleiel, who works for ComponentOne, in depth about Doc-To-Help. Nicky has been a technical communicator for fourteen years and is now a director at large for the STC. I’ve met Nicky several times at Doc Train and STC conferences, and have interviewed her for other podcasts about web 2.0 and the STC.

This podcast is sponsored by ComponentOne, the makers of Doc-To-Help . It’s one of my first sponsored podcasts, but even though it’s sponsored, I’ve tried to keep my same interviewing style.

In this podcast, we focus exclusively on Doc-To-Help. Specifically, we talk about the following:

Help outputs available from Doc-To-Help
Flexibility in choosing your authoring editor
Doc-To-Help’s new ribbon-based interface
Team authoring in Doc-To-Help, including file check-in and check-out
Dynamic help controls available
A sandcastle plugin for SDK and API writers
The appeal of the technical communication field

We also cover a few other topics, such as Doc-To-Help’s approach to DITA and Web 2.0.

To contact Nicky, send her an email at NickyB@componentone.com. Also, feel free to drop me a line at tom@idratherbewriting.com.