Gryphon Mountain is the online home of Ben Minson—technical communicator, writer, and cartoonist. This blog discusses tech comm and other writing topics. More »
One of the things that makes quality documentation on a product is a review process. I think many technical communicators would agree with me, however, that sometimes the process becomes more cumbersome than beneficial. The more people involved, the harder it is to meet deadlines.
While I’m in favor of a limited review process, I think including four certain types of people will maximize the results. I’m not recommending a particular order here.
A few days ago, I posted some thoughts I was having about usability and maintainability. On the surface, they seemed to be two ideas that couldn’t exist together. As I’ve thought further on it, I’ve decided that there may be situations (such as an example I gave in the first post) where this is the case. But on the other hand, the two can go together quite comfortably.
I refreshed my memory on what constitutes usability by cracking open Gurak and Lannon’s A Concise Guide to Technical Communication, a book on tech writing basics that I used in college. (It’s good to return to the basics every once in a while.) Speaking of a technical communication product, they say that people will “use it only if they can find what they need, understand the language, follow the instructions, and read the graphics” (p. 31). Based on these criteria, I’m putting together a series that looks at the places that usability and maintainability not only meet, but also sit down and have a nice dinner together.
On a basic level, simplicity is the key. Users catch on to simple, you can maintain simple, and those who come after you to maintain your work can figure out simple.
We should design and write primarily with our users in mind, but if you work where usability and maintainability overlap, it’s okay to be a little selfish and write with ourselves as considerations, too. If you can create content that benefits both users and yourself, you’re that much closer to making everyone happy, and you’re adding value all around.
Previous: Usability vs. Maintainability in Technical Documentation
A little while back, Michael emailed me an invitation to look at some findings from a study about online experience. I haven’t had a chance to check out the full document yet, but the executive summary contains quite a bit of information. I’ll consider here how some of the findings affect technical documentation.
One point made in the findings is that users’ “enjoyment” of a site is tied closely to how easily they can find the information they want and stay oriented at the same time. I think this is a given for technical communicators; we know that users want to get answers as fast as possible, and documentation must be navigable. Those two factors are easier to pin down than a third: “complete information.”
A few weeks ago, I received an email from a reader who had performed a study about what Web site visitors believe a good online experience is. More on that in another post. But as a technical writer, when I am documenting software, the design bears as much on my experience as it does on any user. So I think about good application design quite a bit.
I once overheard a Web designer say something to the effect that “if an app is designed well, it doesn’t need help,” meaning a help system.
Say what?
A few months ago I posted seven reasons an organization needs technical communicators. This week, a program manager I work with provided a few more ways that technical writers provide value to organizations and projects, so I wanted to pass along his wisdom—with my own discussion, of course. Because I gave seven reasons before, I’ll start with number eight.
In a recent post, I talked about having documentation design reviews. Yesterday, I showed my team a new project I’m working on. I was trying out a new approach, the idea behind which was good. But the team’s feedback helped me turn it into something better—and visually simpler.
We’ve been taking a step back and examining our documentation approach at work. It’s easy, and there is still time to change things, because our team is small. We’re not set in our ways, and we haven’t had an approach or tools dictated to us. One of the main concerns we have is the big disconnect between users and the project team.
Sure, there are interaction designers and business analysts who gather requirements and translate them into user-friendly and user-desired interfaces. At least they try. Many times, even the key stakeholders’ views don’t coincide exactly with the users’ views. It’s a challenge when you’re trying to meet the needs of users who are scattered across the world.
However, as Tom Johnson has brought to our team’s attention, Web 2.0 offers a way for technical communicators to increase their importance as a point of contact between users and the project team. (He posted recently about his experiments with SharePoint to accomplish this goal.) Now I’m not blowing a trumpet and saying that Web 2.0 is a cure-all for the tech writer’s ailments. But there are advantages to it.
While working on a software manual for a project that will soon be launched, I found myself thinking that there weren’t any good places to insert images—the instructions were pretty clear, and if a user is looking at the application while using the instructions, he should be able to find his way.
I realized that I had spent so much time on this project that I was approaching the dreaded mindset of taking knowledge for granted. Like most others, this manual is a reference guide, so users will not be reading from beginning to end, even of their respective chapters. (The material is broken up by role and then by task.) If the current task I’m writing is the only one a certain user ever looks up and reads, then in and of itself, it has to be clear.
It was a good reminder of how, though a wide range of content may be included within the same manual, help system, knowledgebase, etc., that each part needs to be self-contained. These chunks can (and should) refer to each other, but each chunk needs to act like it’s the only one the user will ever read. I should be careful to assume no prior knowledge unless I’m addressing a specific, advanced audience. Writing for the lowest common denominator is the general rule.
The other extreme is manifest in a help system that I inherited. Topics were written in a how-to format, and in most of the instructions, there is an image for each step. In addition to being a monster for maintenance and localization, this setup seems to me to go a little overboard. In many cases, when the user clicks an indicated link, she is going to see the next screen and doesn’t need the help to display an image of that same screen. But when you’re documenting a graphic user interface, whether a Web application or site or the display on electronics, shouldn’t you have images everywhere?
Where’s the middle ground between neglect and overkill?
A coworker asked me today about image resizing, and I mentioned to him a “cheat” I have used that he said he hadn’t thought of. Typically, when you reduce the size of an image in a graphics program, you get smoothing that fuzzes the picture. Not the best result. Sharpening the image then yanks colors apart so that, for instance, black text looks like it’s bleeding yellow and pink.
Early on in our marriage, my wife and I listened to a set of CDs (a wedding gift) from a series of seminars by John Lund, a marriage counselor. Based on years of experience, he had developed the axiom, “Frustration is caused by unmet expectation.”
Now, just think about that statement for a minute in any context you choose. I suddenly recalled this axiom recently when talking with a coworker about a help system I had built and written, and it hit me that in user experience and documentation design, they are words to live by.
Journals by RSS
Journals by Email
