One of the primary tasks any writer or editor must perform is to impose consistency on a manuscript. Consistency is particularly important for technical writers, because it makes the task of writing easier: if you don’t have to develop a new solution each time you face the same problem, you can simply find a solution that works for all occurrences of that problem and use it thereafter. From the technical writer’s perspective, it’s best if you try to build in that consistency right from the start, because it can save you a lot of time both in your initial draft and in your subsequent revisions. Read more of this technical writing article »
Save Time by Mastering the Basics: Efficient Movement within a File
We technical communicators aren’t so different from the rest of the world: we tend to reach a comfortable plateau in our skills, and so long as we’re meeting our deadlines reasonably efficiently using those skills, we tend to lack the motivation to pay close attention to what we’ve been doing and look for improvements. But what if I told you that you could potentially save 15 minutes per day without doing anything more arduous than mastering three new keyboard shortcuts? Read more of this technical writing article »
Uprooting Entrenched Processes: Process Improvement Using the Kaizen Method
At some point, you’ve undoubtedly found yourself following a procedure that didn’t seem to make sense, or that made sense but was hideously inefficient. But contexts evolve, and procedures gradually drift out of synch with the daily reality employees face. Sadly, most organizations have no formal process for updating their procedures to account for this drift. Here, I’ll boil down my Intercom article on the Kaizen method and chapters from my book into their essential elements, namely the conditions required for successful organizational change and how you, as a technical communicator, can participate in those changes. Read more of this technical writing article »
The Five W’s of Online Help for Tech Writers
Lately, I’ve become a vocal critic of modern online help for a variety of reasons. But my biggest criticism is that despite the usability improvements offered by context sensitivity and modern indexing tools, many help systems become formulaic descriptions of procedures that fail to truly address the needs of their users. This problem arises partially [...] Read more of this technical writing article »
The Needs of the Many
Editor’s Note: The following piece by Geoff Hart is part of our collection of “classics”–articles that stand the test of time no matter how many technologies come and go. Every technical writer has been advised to understand the audience before documenting a product. Traditionally, this has meant understanding the needs of the product’s immediate users; [...] Read more of this technical writing article »
Getting Feedback on Our Work
November 2009, I attended an STC Montreal presentation by John Druker, from SAP Labs Canada. Like many of us, John struggles with the task of getting feedback from his readers about the documentation that he and his colleagues produce. Unlike most of us, John has made a considerable effort to find ways to get that [...] Read more of this technical writing article »
Conquering the Cubicle Syndrome
Editor’s Note: The following piece by Geoff Hart is part of our collection of “classics”–articles that stand the test of time no matter how many technologies come and go. I’m going to violate one of the cardinal rules of technical writing, and alienate my audience right off the bat: I’ve never worked in a cubicle. [...] Read more of this technical writing article »
Personas and the five W’s: Developing Content that Meets Reader Needs, Pt. 2
Part II: Applying the five W’s In the first part of this article, I introduced the concept of personas, a tool for creating a detailed description of the people we’re writing for. An ideal persona becomes so real that we intimately understand who that person is, what their needs are, the problems they face—and therefore, [...] Read more of this technical writing article »
Personas and the five W’s: Developing Content that Meets Reader Needs, Pt. 1
Part I: What’s a persona? Most documentation written by professional writers, whether printed or online, is well written and easy to navigate, but in my experience, an unfortunately high proportion omits important content or provides inadequate depth of content. Worse yet, the information may seem perfectly acceptable from a textbook perspective, yet fails to reflect [...] Read more of this technical writing article »