Editing for tech writers

Tech writers don’t just write, we frequently also edit what our peers have written. As Tom Johnson recently tweeted:

Can’t decide if the technical editor role is dead or if technical writers have evolved into this role as their new default.  8:40 AM Apr 23rd

I wouldn’t call it a “default role” for us writers, though the “pervasive idea in companies that ‘anyone can write'” creates more demand for this role (paraphrased from another tweet by Tom three hours later).

I’ll gladly edit the work of another tech writer (and rely on their feedback in return), but I’m less likely to “clean this up by noon”: I’m not grammar boy, and if anyone can write, then anyone can also clean up behind himself… If and how I edit depends on the situation. But what do I mean by editing?

(And what do I mean by that photo? Nothing in particular. Except maybe: How do you illustrate editing? :-))

Editing 101

When it comes to technical editing I have three heroes: Robert Van Buren, Mary Fran Buehler, and Jean Weber. Robert and Mary put together the ultimate tech editing guide back in 1980, called Levels of Edit. An STC edition from 1992 is apparently out of print, but there’s still a summary and a PDF version out there. Their booklet is the most comprehensive and best structured guide to tech editing that I know. They distinguish nine (!) types of edit:

1. Coordination
2. Policy
3. Integrity
4. Screening
5. Copy Clarification
6. Format
7. Mechanical Style
8. Language
9. Substantive

Depending on how thorough your task and how much time you have, you go through all or only some of the levels. In fact, they suggest five different levels of edit for different purposes of a document. Unless you create a production edit for a printing house or publisher, you will probably omit types 1 and 5. The others may be more or less relevant, depending on general policies and what kind of document you’re editing.

I find the nine types of edit so clear and well-structured, because they help me to stay consistent and focused in my editing:

• When I do an integrity edit to make sure that the table of contents and index are up to date and show the correct page numbers and that all lists are numbered correctly, then I don’t want to worry about misapplied templates, line breaks, text justification and alignment.
• When I do the mechanical style edit to assure compliance with the corporate style guide, I don’t want to haggle with Oxford commas and dangling participles.

Yes, it does mean that I go through the same document repeatedly, but I find that the additional time spent scrolling or turning pages is made up by the better focus.

Editing the work of others

You can edit your own work, but I don’t recommend it: I find I’m too entangled in my writing, constantly tempted to fix an odd phrase here, a less than perfect table there. If at all feasible, have your work edited by someone else, and edit the work of colleagues.

This is where my third hero Jean Weber comes in (no relation to me): Jean knows all about how to work with editors – or, if you’re an editor, how to work with people who write. She also pointed me towards Levels of Edit.

Jean is in Australia and, according to her website, retired from paid work. But she’s so generous, she shares her knowledge and experience. I found three articles especially helpful:

• Working with a technical editor – where she explains what tech editors (or people filling that role) do and feasible scenarios to use them
• The role of the editor in the technical writing team – where she describes what people expect from editors, what they really do and how they interact with other documentation roles
• Beyond copy-editing: the editor-writer relationship – where she shows how the editing role can be filled successfully

Your turn

How do you edit? How are your documents edited? Do you edit your own work or someone else’s? Feel free to share issues and insights in the comments.

Advertisement

Your perspective shapes your work and your future

For tech writers, perspective is very important. How you look at your job determines what kind of documentation you deliver, how valuable it is, and what kind of success you’ll have.

Gaining perspective in stages

In more than 10 years of writing full-time, I’ve gone through three successive stages:

1. Serving the product of the company which pays me
2. Serving the company which pays me
3. Serving the customer who pays the company which pays me

This development has led me from introverted writing to extroverted content management, from specific manuals to abstract content strategy. Each stage gets more difficult and increases the demand for managerial thinking, even though you may not formally manage anything but your documentation and yourself. (See my previous post “Manage documentation as a lone writer“.) But each stage also adds more value to the documentation you produce – and hence for your company and for you, too.

Which stages are available to you depends not only on your motivation and skills, but also on the expectations on you and your job. In fact, a mismatch between your perspective and outside expectations on your job is a problem. You and your boss may talk about documentation, meaning different purposes and different ways of doing it.

Serving the product

This is the conventional, old-fashioned perspective: You create a description of the product and all its features. This is fairly easy because the selection and structure of the documentation is largely determined by the product. In software documentation, you often see one section per menu or menu item.

This documentation adds little value beyond spelling out what’s where. Your readers learn which function does what, but they may still have to learn how to use the product for their purposes. User of a word processor who try to create a book in ready-to-print PDF with table of contents, headers, footnotes and an index are easily at a loss with disjointed instructions about page layout and reference marks.

Serving the product sells tech writing short, since we can do so much more. With this perspective, documentation is often seen as a necessary evil. People who think no one reads it outnumber those who use it. I’ve seen tech writers stuck with this perspective; changing this perspective  to one of the other stages is fairly difficult and requires motivation, persistence and self-marketing – or even a new job…

Serving the company

This is often an implicit, informal task for tech writers or other job profiles, especially when the company is better at producing information than at structuring and maintaining it. If you hear: “We really should have a glossary,” this is your company. If you’re in charge of the glossary, you’re serving your company. With this task, you spend a lot of time assembling and structuring existing information about the product, its uses, benefits and markets. The role often feels like a research librarian.

This adds some value, because users and the company get a more coherent idea what the product is and how it should be used. You literally help the company “make up its mind” and stay on message about the product.

Serving the company gives a tech writer more freedom than serving the product – but also less structure within which to work. Even though it feels vague and in limbo, it can actually be a pretty stable and satisfying position if you feel you can successfully apply many different skills. This can also be a great position to re-orient yourself and aquire additional skills. It tends to get dodgy, however, when the company goes through fundamental changes, because this role lacks a clear profile and you may find it difficult to prove your worth.

Serving the customer

This is the task-based perspective on documentation: You show the user how to achieve his tasks with the product. You combine elements of the previous two perspectives. You take the features and functions of the product, combine them with the use and markets that the company intends, and translate it all into the user’s language and purpose.

This is the most difficult of the three perspectives, but also the most valuable. Your documentation helps users to get stuff done. It ensures that the product is actually as successful as sales and marketing claim it is. You’re rooting for the actual standard user – not the potential users who haven’t bought the product yet, or the complaining ones of customer service who need specific help.

Serving the customer raises your tech writing profile as the users’ advocate and demonstrates best which value you add – but it won’t make you universally loved: As you champion usability, you compete with marketing and product management which push for benefits they want to sell and with development and with production which focuses on the specific functionality that they can produce efficiently. However, if you can show that improving usability pays off in higher sales or lower support costs, you can directly contribute to the company’s success.

Your turn

Which perspective do you think is most useful for tech writers? Are there others that I’ve missed? What’s the best way to get yourself and your boss into the one you prefer?

Three more tips for reading outside…

… reading outside the tech writing box, that is… 🙂 After the previous post, three more items crossed my way which I want to recommend:

1. My friend Scott Nesbitt has a similar and interesting post on his personal blog which I’ve discovered only now… Scott recommends books, articles and blogs and says what he gets out of them, so check it out!
2. I’ve since started another book by Alain de Botton which I can recommend wholeheartedly: The Pleasures and Sorrows of Work, a reflective and well-written “hymn to the intelligence, peculiarity, beauty and horror of the modern workplace and, not least, its extraordinary claim to provide us, alongside love, with the principal source of life’s meaning.” It shares Botton#s knack for observation and style with the previously mentioned Art of Travel.
3. And speaking of writing about jobs and occupations, I also liked the colloquial collection of biographical portraits by Po Bronson What Should I Do With My Life?

Reading outside the tech writing box

Can reading around improve your technical writing? Many writers recommend to read a lot, but discriminately: Margaret Atwood, P.D. James and A.L. Kennedy do,  Annie Proulx, Zadie Smith and Sarah Waters do too, when the The Guardian asked them for “Ten rules for writing fiction”. But does this apply to technical writing, too?

It took me a while to figure it out, but I think reading “outside the tech writing box” helps my tech writing. By “outside the box”, I mean reading beyond an immediate purpose, so I’m excluding writings about tech writing, such as books or blogs, specifications and style guides.

Technology journalism

Most effective for me is well-researched, well-written technology journalism:

• It emphasizes stories and the people behind them and reminds me they are more important in my writing than the latest feature bonanza.
• It helps me to focus on personas and my audience and reminds me where other people in the industry are at – or where they may be headed.
• And with some luck, it’s fun to read and well argued and remind me to try and be engaging in my writing where appropriate.

The kind of writing I mean can be found in print and online in Wired, Slate and Salon, in the New York Times and the New Yorker, the Chronicle of Higher Education and the Columbia Journalism Review, in other blogs and magazines and newspapers.

If you like books, the annual anthology The Best of Technology Writing 2007, 2008, 2009 collects about two dozen articles each year that are frequently worth your while – especially since the first two volumes can be read online for free.

Let me give you a few examples which I think stand out above the majority of magazine articles and blog posts:

• Jeff Howe’s “The Rise of Crowdsourcing” (Wired,  June 2006) first explained to me how off-shoring and outsourcing got a new twist with crowdsourcing of stock photography (such as seen in this blog), serious R&D and Amazon’s Mechanical Turk program.
• John Seabrook’s “Game Master” (New Yorker, 6 Nov 2006) tells the story of Will Wright, the creator of video games such as Sims and Spore.
• Emily Nussbaum’s “Say Everything” (New York Magazine, February 2007) showed me how people who are ten years younger than me have a completely different concept of privacy.
• Dana Goodyear’s “I [Heart] Novels” (New Yorker, 22 Dec 2008) introduced me to cell-phone novels originating in Japan.
• Clive Thompson’s “Brave New World of Digital Intimacy” (New York Times Magazine, 5 Sep 2008) provides an in-depth look at Facebook and portrays its founder Mark Zuckerberg.

What else?

If you’re focusing on a specific industry, you can probably also find outstanding journalism there which is worth hunting down. I’m in financial and banking software. So trying to find good articles with an expiration date beyond the next quarter has been especially interesting… A good starting point for me was an anthology by Michael Lewis and McSweeney’s called Panic: The Story of Modern Financial Insanity with pieces written between 1987 and 2008.

Beyond that, I find my reading cannot inform my tech writing much. Recently, I really liked Alain de Botton’s The Art of Travel for its insights what motivates both travel and art and its concise arguments backed up by well-written examples.

I’m also fond of E.M. Forster’s style and handling of plot and character in A Room with a View. These books, as well as many others, engage me and enrich my life – and remind me that there’s a reading life outside of my job… 😉

What do you think? Can reading help to improve your technical writing? What books, stories or articles have you found inspiring or helpful?

Readability vs. usability in manuals

The new manual is harder to read – but easier to use.

This is the feedback a colleague tech writer got from one of his reviewers. The manual had previously had a lot of screenshots, so it was easy to follow along.

My colleague revamped it to use fewer screenshots, but more structured text. As a result, the new manual was deemed to be easier to navigate and more useful in a wider variety of use cases.

I thought the feedback is spot on: Unless I’m writing a tutorial where I specifically lead users by the hand, I’d always take usability over the sheer readability. Usability can ensure that users find it easy to navigate the manual and find the information that applies to their current need.

The kick ass curve

How long do your users spend in the “I suck” (or “this product sucks”) zone? Once they’ve crossed the suck threshold, how long does it take before they start to feel like they kick ass?

I don’t know anybody who illustrates the motivational angle of documentation better than Kathy Sierra. Her post “Attenuation and the suck threshold” from October 2005 has one of the most insightful, funniest curve charts I’ve ever seen. It may not apply to everything you’ll ever write, but I recommend it as a fresh perspective.