Alan Brandon

The article I wrote about Honeywell’s new Windgate wind turbine made Gizmag’s Top 20 for 2009!

The article originally ran in June, and according to Gizmag’s database logs it was one of the top 20 most read articles during 2009.

Thanks to everybody who clicked through to read the article. I enjoy the work I do for Gizmag, and it’s nice to be noticed when folks find my work interesting.

I got a lot out of Scott Abel’s book review of DITA 101: Fundamentals of DITA for Authors and Managers on The Content Wrangler — and I haven’t even read the book! I think Scott really nailed the progression of structured writing over the last decade or two.

… The personal computer, the World Wide Web, desktop publishing, … have transformed not only the way consumers interact with content, but these advances have also altered the way professional communicators work. … Technical writers and editors have been forced — like it or not — to move to a more formal method of creating content, often for a global audience. Gone are the days of the free-for-all approach to creating technical documentation products one-at-a-time … The advent of the Extensible Markup Language (XML) and rapid adoption of topic-based content standards like DITA have forced [technical communicators] to separate content from format and end our addiction to desktop publishing. Today, technical communicators must learn to write modular, topic-based, context-independent content using a new breed of authoring tools.

While Scott focusses on DITA (the subject of the book he is reviewing) I would add Information Mapping to the modular tools and techniques that are enjoying a resurgence in the write-once-publish-many boom.

The modular approach to technical writing is nothing new, although the names of the concepts have changed and shifted. I remember HP’s writing system was based on modular building blocks of information.

I just rediscovered John Hewitt’s excellent PoeWar blog, and I found a great article about trainers as a powerful resource for tech writers.

If you want help creating documentation, get to know the trainers. I am frequently amazed at how little communication some companies have between the training and the documentation departments. In many cases, the training departments develop their own materials…. More than once I have sweated over creating a procedure, only to find out later that it was already in the training materials.

Trainers not only get to know the company’s products, they get to know the customers. For many (shortsighted) companies, the trainers are the closest thing you have to a usability team. They walk through the product in front of the clients, who inevitably have questions about the process or come up with scenarios that point out the limitations of the product.

Hewitt’s opening paragraphs reminded me of two recent gigs, and the contrasts in their relationships between the trainers and the writers.

At one company, the tech pubs manager arranged for a special training class just for us writers and editors. The entire department attended and we had a custom presentation about the upcoming release and the overall product line. We got to pepper the trainers with our particular writer questions about the customers and how the docs were really used (or not used).

At the other company, a large corporation with a broad product portfolio, we were essentially denied any chance to interact with a trainer at all. The company had an extensive “university” with many training courses and instructors that traveled to the various corporate campuses. Unfortunately our department policy only allowed us to take courses that were free. All of the live training classes had a cost associated with them. But these were internal, inter-department charges. The money didn’t leave the company. Nevertheless we were limited to watching prerecorded tutorials or narrated PowerPoint decks with no opportunity to ask questions.

At the first company I was able to hit the ground running with a good view of where my project fit into the company portfolio and into the overall customer experience. At the second company, it was much harder to know how the features I was writing about were relevant to the customer.