One of the tasks that people in our wacky profession seem to wind up doing is writing or rewriting error messages and text in an application’s user interface. Not that I’m complaining — it’s a job that needs to be done, and why not get the right people to do it right?
Doing that sounds simple. Often, it isn’t. There are times when it’s not immediately obvious what that text should be. And, at least in my experience, technical communicators get put on the spot to come up with something during a meeting or while chatting with developers and QA.
In a situation like that, you can’t always come up with clear and concise text on demand. But often, you need to come up with something. And quickly.
The easiest way that I’ve found to do this is to brainstorm ideas on my own. It’s a very effective technique, and I can usually come up with something that’s better than just usable very quickly.
A while back, I attended a very interesting seminar given by a couple of consultants in Toronto. The seminar was an overview of various techniques to help kick start your creativity. It was an interesting experience, and I learned a number of interesting techniques.
One of techniques that I really dove into mind mapping. While mind mapping isn’t new to me, in the past I wasn’t really as comfortable as I should have been with it. During the seminar, something clicked and I finally saw how I could use mind mapping to effectively plan my writing. Not just the freelance writing that I do but any kind of writing, including technical writing.
Aaron and I advocate minimalism in documentation. Our definition of minimalism differs slightly from how some people may define the term, and we take some heat for it. But no matter how you define it, the aim of minimalist doucmentation is always the same. To give user the information they need in the most concise, readable, and accessible way.
Sometimes, though, minimalism can go a bit too far. Craig Haiss wrote a good post about this a while back. And I ran into some documentation that was just a bit too minimal recently.
Last week, I bought a Nexus One smartphone. Stand me a milkshake and I’ll explain why. Now, a smartphone isn’t the most complex gadget out there. You expect the documentation that comes with the device to be skimpy. It was in this case. Maybe a bit too skimpy.
Lately, I’ve been chatting a bit with a some people who use MadCap Flare, or more specifically the MadPak Suite. Something that came up more than once in those chats was MadCap Analyzer, a tool for finding problems in a Flare project and for making various suggestions.
Surprisingly, not everyone I talked to has used Analyzer. It’s a useful app, and whenever I work on a project in Flare I run Analyzer over it at least once.
I also found that most of the people I talked to only focus on Analyzer’s variable and snippet suggestions. Only a couple have taken a close look at Analyzer’s index keyword suggestions. Those suggestions are a potentially useful way of beefing up your index.
Lately, I’ve been thinking about what makes an caution or warning in a piece of documentation effective. While thinking about it the other day, I recalled what was probably the most effective warning I’d ever seen.
It was on a flight to Singapore in the early 1990s. Like everyone else on the flight, I had to fill out a customs form. At the bottom of the form, in bold red letters and all caps where the words:
DEATH FOR DRUG TRAFFICKERS UNDER SINGAPORE LAW
I’m not a drug trafficker. I’ve never had any ambitions to become one. If did, those seven words would have made me reconsider my choice of profession. And quickly.
Radio and documentation. It sounds like a strange, if not incompatible, mix. But if you think about it for a moment, the parallels are staring you right in the face.
When writing documentation, my ideal model is a good radio report. Sounds kind of strange, doesn’t it? If you think about it for a moment, though, a radio report has all the elements of a good piece of documentation:
- It’s short and to the point
- Where necessary, it contains just enough background to orient the listener
- It contains all the important facts, compressed into small space in time
When crafted properly, task-based documentation does the same thing.
How to do it
That could (and has been) a book in itself. As I recall, more than a couple of books. My own experience in radio is limited. In my first year at journalism school I took the mandatory course in radio, and later did some freelance work for CBC Radio. To say that I’m rusty is a bit of an understatement.
But the Internet, as it often does, comes to the rescue. Here are some good resources on writing for radio:
Will this really help?
I think so. Exposing yourself to other writing styles, specifically non-fiction styles, can help improve your technical writing. Remember that technical writing isn’t just single sourcing, DITA, and all of that. It’s about words. That’s why it’s called technical writing … If you can distill all that information into a compact and easy to read format, then all the tools in the world aren’t going to make your documentation useful or usable.
Thoughts? As always, feel free to leave a comment.