Month: July 2006

10 DITA Lessons Learned From Tech Writers in the Trenches

This exclusive and informative top ten list is based on interviews conducted by with technical writers at more than 20 software companies—tech writers that are actually using DITA to create documentation today. It’s jam-packed with useful advice, practical tips, honest warnings, and lessons learned. No marketing blabber. No hidden sales agenda. No name dropping. Just straight forward and useful information no software company is likely to share with you any time soon. Ready? Let’s begin… #10 – DITA Is NOT A Magic Wand DITA is a standard data model not a magic wand that automatically solves all your problems. DITA makes some things easier but adds its own issues as well. As with any XML project, the most effective solutions will be built by someone who has proven knowledge and experience. DITA does not change this. #9 – Don’t Fall In Love With Software Far too many technical writers fall hopelessly in love with an authoring tool for no apparent business reason. Software love affairs are good for vendors because they convert regular, ordinary writers into mindless, unpaid software evangelists. Love affairs of this sort are bad for organizations that employ technical writers because they prevent us from asking questions about our own choices, our own motivations, and the impact our personal preferences may have on the organizations for which we work. Love is an emotional thing, while...

Read More

Tech Writers: Are You A Future Document Engineer?

In “Document Engineering: Analyzing and Designing Documents for Business Informatics and Web Services”, Robert Glushko and Tim McGrath write, “Practitioners of document engineering will most likely come from other disciplines from which document engineering was synthesized. The principles of document engineering seek to find a balance between technology and business, between process and information, between bottom-up and top-down thinking, and between concepts and implementation. Successful documents engineers,” the authors say, “will do the same.” Read my recent book review in the July 2006 The Rockley Bulletin. Then, put on your headphones an listen to Jon Udell’s interview with Robert Glushko. If you’re ready for a career in document engeering, you’ll soon find yourself purchasing the...

Read More

When You Need Documentation, Don’t Hire An HVAC Contractor

When you need technical documentation, don’t call an HVAC contractor to the rescue, despite what the Pocono Record says. In a recent “Write to Know” column, the paper incorrectly (albeit humorously) stated: “ASHRAE is the American Society of Heating, Refrigerating and Air-Conditioning Engineers, a nonprofit technical writing organization.” For the record, ASHRAE has nothing to do with technical writing. Instead, it’s “a nonprofit technical organization whose 55,000 members influence the direction of heating, ventilation, air conditioning and refrigeration (HVAC&R) technology by creating industry standards and recommended procedures and guidelines, developing research and writing technical information.” The Society for Technical Communication (STC), on the other hand, is a nonprofit technical writing...

Read More

Buzzword: Targeted Completion Date

From the buzzword of the day file: Targeted completion date – “A comforting term that gives the impression a project will be finished by a certain date (but everyone involved knows there’s no chance in hell of it happening).” If you found that entertaining, subscribie to the mailing...

Read More

The Impact of Globalization on User-Interface Design

In The Impact of Globalization on User-Interface Design, TC World writes: “Did you ever try to use a machine that has been programmed in a foreign language? Or perhaps, even with an unfamiliar character set? Suddenly everything seems to be different although only the language has changed. This is the situation faced by many foreign users that work with German...

Read More

Receive exclusive access to members-only content, invitations to in-person and virtual events, and sneak peeks at new tools and emerging technologies. Join today!

Join Now!





Pin It on Pinterest