In my last post on wikis, Mark Baker added an astute comment: I’m not a wiki fan myself — I’m a structured text guy bred in the bone — but I am fascinated by the trend, and by the variety reactions to it. Wikis started more as a cultural statement than a technology. They were a tool for the democratization of content, the intent being … more »

It’s been about 9 days since my last post, and yesterday my colleague leaned over and asked why I hadn’t been posting — was something wrong? He himself has been working on a novel, so he hasn’t posted anything for a month. No, nothing is wrong. I always chuckle when I see blog posts in which people apologize for not posting on their blog, or … more »

If you want to be able to sort information by various classification schemes, such as by most popular, or by role, or by problem, your content has to be chunked in a granular enough way to facilitate the various means of sorting. Consider a work that is one large book, with no chunks at all. In that case, it would be impossible to sort anything, … more »

My colleague Ben Minson wrote a post about why tripane help is a relic of the book-paradigm documentation age, and how it can limit us from taking advantage of other web technologies. See Why I Don’t Like Tri-pane Help. As a quick definition, tripane help is the standard webhelp HTML output that has several frames — the table of contents pane on the left, the … more »

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, … more »

With my recent reflections on long versus short text, a comment by Michael O’neil made me wonder whether the “reading to do” mode equated with DITA’s task type, and whether the “reading to learn” mode equated to DITA’s concept type. 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 … more »

Sarah O’Keefe at Scriptorium is running a survey on structured authoring. You can take the survey here. 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 … more »

Scriptorium is presenting a free webinar on the DITA features in Madcap Flare this Tuesday at 11 a.m. EST. Here are the details: Presented by Sarah O’Keefe, this webcast demonstrates using MadCap Flare to create WebHelp from DITA-based content. Topics covered include: Importing DITA content into Flare Map file handling Cross-references and links Relationship tables Conrefs Conditional processing By the way, you can keep up … more »

In a recent email to me, Jake from California (not his real name or location) writes, I’ve spent most of today exploring the world of technical writing, and I find that you’re very central and visible. I’ve read, listened to, and watched a good deal of content you’ve produced, plus viewed snippets of threads on the STC listserv where you either weighed in or were … more »

Right now I’m immersed in an online help project in which I’ve been using Madcap Flare. Here a few tips I’ve picked up in the past month or so.

Eddie VanArsdall reviews three books on DITA. If you’re interested in adopting DITA, or even if you just want to borrow some of its best practices, check out one of these books — by Rockley, Vazquez, and Comtech.

Sarah O’Keefe at Palimpsest is offering several webinars on DITA and XML. I attended a webinar by Sarah before. It was clear, straightforward, and engaging. I definitely recommend her.

Lately I’ve been creating context-sensitive help for an online application. As part of my strategy, I’ve been trying to follow Theresa Putkey’s advice in “Usability in Context-Sensitive Help.” In her article, Theresa recommends providing more than just the steps for a specific task in the context-sensitive help window. Instead, she says to show more contextual links, including answers to why, when, and who questions, because … more »

It seems most of the conversations in our industry today revolve around value. If you go to stc.org, the large graphic at the center of the site says “The Value of Technical Communication.” (Given the recent events in the STC, to me the graphic really reads, “The value of the STC organization.”) At any rate, technical writers have been talking about demonstrating value to employers … more »

Content Theory: Sheep and Chaos — MK Anderson. Keith Anderson writes about the need for technical communicators to focus on user needs and the user experience as their starting point. Does DITA fulfill this focus? Not in the eyes of the user. Users want better search and social networking.