Quick Reference Guides: The Poetry of Technical Writing

Quick reference guides 1.0 → Quick Reference Guides: The Poetry of Technical Writing 1.1 Quick Reference Guide Formats -- Tips for Finding Attractive Layouts 1.2 STC Presentation this Thursday: "Quick Reference Guides: Short and Sweet Technical Documentation" ...

The Intersection of the Personal and Professional, or, Why My Attempts at Nonfiction Essays in Grad School Bombed

I wrote this post for Poewar.com last year, but I like to keep my own writing consolidated on my site, so I've added it here. Literary nonfiction gets its energy, Richard Locke says, from the intersection of the personal and professional. The tension and appeal of literary nonfiction comes from the interplay between the writer's personal experiences and the topic he or she is exploring. Richard Locke headed the Literary Nonfiction Writing...

Approaching Help as Solutions to Problems — An Interesting Format from the CSS Cookbook

At Borders or Barnes & Noble, I often browse the computer books to see the different ways writers approach help material — especially how they approach the same help material. The other day I wanted a book on CSS, so I pulled four available CSS books off the shelf and began browsing them. Each book looked respectable, but the CSS Cookbook, by Christopher Schmitt, had a unique format that caught my attention and convinced me to buy it....

Interview with Me in TechCraft

Rahul Prabhakar, editor of the TechCraft newsletter, which accompanies the Technical Writers of India listserv, published an interview with me in the latest issue (June 2008). You can read it here: Techcraft e-Newsletter Volume 38 June 2008. It's in the "Spotlight" section near the end. (You can also log into Yahoo and read it here by going to the June 2008 folder, but Rahul gave me permission to post the PDF directly.) Tech Writers of In...

"What's Next?" -- A Nice Way to End Help Topics

At the end of many topics in Flare's help, a What's Next? section appears. For example, in a topic on Creating a Table of Contents, the What's Next? feature guesses what you'll want to do next -- enable the table of contents in your target. See the following image. Having used Flare's help for a while, I really like this What's Next? feature. For me, it works better than the See Also references, which are more common. (One time I asked a...

14 Widespread Myths about Technical Writing

Jefferson McClure added a thought-provoking article link on WriterRiver.com titled "Myths of Technical Writing." The article is by Bob Doyle and appears on the dita.xml.org wiki site here. In the article, Doyle and other wiki contributors mention 4 myths about technical writing: The GlueText Myth The Stem Sentences Myth The Front-Matter Page-Numbering Myth The Callouts on Graphics Myth You'll have to read the original for the details. ...

My Compromise with SharePoint -- What Works and What Doesn't

In a previous post, I mentioned my desire to use SharePoint as a help authoring platform because it provides a Web 2.0 experience that is company-sanctioned. SharePoint not only has blogs, wikis, and RSS feeds, but also integrates with Active Directory, Outlook 2007, and has integrated search across all content. However, the more I tried to use SharePoint as a help authoring tool, the more problems I ran into. SharePoint doesn't handle ro...

My WordPress Site Was Hacked

My site was hacked today. Usually when someone says "my site's been hacked," the first response is, are you sure you didn't screw something up yourself? Yes, I'm sure. Someone twittered that my tinyurl was showing a login page. Actually, for me it showed the install page below: But I hadn't been upgrading or installing anything. Something was definitely wrong. I wondered if it was a hacker, so I searched the WordPress forums and found a...

Customizing Your SharePoint Site? Read These 10 Concepts/Gotchas First

Preface: I wrote this post after spending a month digging deeply into SharePoint, attempting to customize and brand the site as well as migrate all my help content to it. If you're totally unfamiliar with SharePoint, this post will not get you up to speed. But for those embarking on a SharePoint customization challenge, most likely you're already familiar with SharePoint. Reading these ten concepts and gotchas will help you avoid some of ...

Podcast: Five Books to Add to Your Technical Communication Library

Listen here: In this podcast, Heidi Hansen takes 15 minutes to discuss five books that she read over the past year and published book reviews for in the Technical Communication journal that STC publishes. Rather than being an interview-style podcast episode, this audio was recorded by Heidi at her home PC and quickly traverses the five books so that you can learn some key concepts about each book. The following are the f...

The Kind of Documentation Users Really Want

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce. But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually t...

"How can I become a successful TECHNICAL WRITER?"

K. writes, Dear Mr. Tom Johnson, I am a Post Graduate in English. Recently I am working in a leading public house as writer. How can I become a successful TECHNICAL WRITER? Please reply me as soon as possible. K. Dear K, The best thing you can do to develop your skills and ability with technical writing is to actually do some technical writing. Find an open source project, such as WordPress.org or Pligg, and write some documentation for i...

Systems that Get Better the More People Use Them

In Publishing 2.0, Tim O'Reilly says Web 2.0 is "any network effect that makes a system better the more people use it." Web 2.0 isn't just user-generated content; it's harnessing the collective intelligence of your users to make your system better. O'Reilly's definition is intriguing because it's the opposite of the natural law of use. Your car doesn't get better the more you use it. A music track doesn't get better if more people listen ...

Announcing WriterRiver.com, a Digg-like Social News Site for Technical Communicators

Update: I have since revised the writerriver.com site with a different implementation. This new version is more like Twitter than Digg. The concepts are still mostly the same, except there's no voting. I've been a long-time reader of Digg.com, but just last week it dawned on me that it would be really great if there were a Digg-like site for technical communication. So I decided to create one. It's called WriterRiver.com and it's pretty m...

Technical Writer as Conversation Stopper, and Other Notes from the STC Summit in Philadelphia

On the eve of the highlight conference of the year, I'm out with two colleagues at a grill in Philadelphia, and the waitress is chit-chatting with us more than usual when I mention, in the context of the conversation, that we are all technical writers. "So you like work for the government? Tell me no," she says. And then in a split-second, she walks off, completely uninterested about our profession. Through this and many other experiences...