How a degree helps a technical writer

A college degree can help you in technical writing, though maybe not in the ways you expect.

How relevant is a college education for the field of technical communication? A couple of very good and influential tech writing blogs have recently discussed this issue:

The question is both pertinent and impertinent, because Tom and Ryan frame it in a way that devalues college education [… at least in the specific program they are criticizing, see Ryan’s comment below. 18 Nov 2010]. Tom says tech comm “should not be taught in the context of an English department, because [it] is not understood or encouraged in traditional English curricula.” Ryan says he’s gained more useful knowledge in 5 months in the job than in his entire time in the tech comm MS program. I cannot argue with their experiences, and I cannot hope to convince them otherwise.

To help anyone with similar questions who’s in college now or has recently graduated, I can offer my own alternative assessment: How a college degree helped me become a passionate and, I dare say, good technical writer.

What I sought

Computer Science and Business as a combined major was how I started college. I sought to learn how to build software and how to run a business. What I got was learning by rote, too much how it’s done and not enough why and how it could be done better. I dropped the major after a semester.

I had embarked on rational and reasonable education and found that my heart wasn’t in it. I just couldn’t see myself spending several years getting a degree as a means to an end. I expected college to teach me something that was interesting in its own right, not a promise that I could apply it in a future job, or maybe not.

American Studies is what I declared as my major after two weeks of soul searching. That’s where I found my academic home. The curriculum was heavy on literature, social history and culture. The emphasis was on understanding what holds the USA and its culture together, to come to terms with its cultural and artistic developments, and to use whatever academic theories could be made useful.

Over ten years ago, I’ve received my M.A. in American Studies. I’m a technical writer by choice and practice, with the heart and the outlook of an Americanist.

What I learned

In American Studies, I learned a lot of things. Almost all of them do not directly relate to technical writing. Here are some things that I’ve found useful and applicable as a technical writer:

  • How to write long, coherently argued, understandable papers in correct English. It took me a long time to get it right. It took me longer yet to realize the importance of tailoring my message and language to my audience. And it took me even longer to realize that all this combined is a rare and marketable skill.
  • How to explain something that defies explanation to people who think they already know how it works. After you’ve ever tried to explain America to Germans who have it all figured out from movies and news media, writing user manuals is actually pretty easy. Most products I’ve dealt with are less complex than a country of 310 million people, even if you only regard the most recent 400 years.
  • How to cope with complexity. Literary studies can appear pretty neat, especially when you deal with only one author or one book. Studying a country and its culture is a more daunting task, not least because the people carry on so, with no regard for your studies. Trying to keep your insights reconciled with an ever-changing reality is a good preparation for your survival in large corporate environments and their organisational quirks.
  • How to organize to finish. Formulating a thesis and then framing and arguing it was part of my later assignments. That was a good preparation for writing user manuals from scratch. The “thesis” in that case is the easy part. The customer wants to do stuff with the product and look cool while doing it. But the rest is again up to the writer: Framing the text in a context of use, consulting all available sources, explaining it in the most understandable and most efficient way.
  • A turn of phrase occasionally: That a question can be both pertinent and impertinent (see above) is something that I learned from Thoreau’s Walden, the second paragraph of the “Economy” chapter to be precise.

What I know now

A college education can work very well for you, if you take it for what it is and don’t expect something that it isn’t. Stanley Fish makes a very astute argument for what a university can be and do:

When it comes to justifying the humanities, the wrong questions are what benefits do you provide for society (I’m not denying there are some) and are you cost-effective. The right question is how do … your program of research and teaching fit into what we are supposed to be doing as a university.

It’s important to realize that this kind of education comes with no guarantee: It guarantees you neither a job, nor happiness, nor that you’ll always be right or make the right decisions.

But it gives you the tools to gather information, take responsibility and make the decisions that affect your life. In short, such an education can give you hope. In the words of Václav Havel, writer, dramatist, and the first President of the Czech Republic:

Hope … is not the conviction that something will turn out well, but the certainty that something makes sense, regardless of how it turns out.

Your turn

What did you get out of a college education? Was it useful for immediately applicable skills? Was it instrumental to become who you are? Or was it a waste of time?

Advertisements

What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true:

Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall.

And here’s the guy who was married to both, Kris and Robert… 🙂

How and why to estimate writing efforts

Estimating your writing efforts and deadlines is difficult, but essential.

Can you reliably estimate the time you need to write documentation? And the date when you can deliver? It often seems a daunting task because it depends on many external factors:

  • The quality of specifications and designs.
  • The availability of the finished product.
  • The accessibility of subject-matter experts.
  • The punctuality and diligence of reviewers.

It also seems futile to spend time estimating efforts when you know you don’t have enough time anyway. But even though it’s difficult and takes time, I recommend that you do it.

Why estimate?

If you don’t do it, someone else will make assumptions about your schedule. Even if you’re just left with the ever decreasing time between delayed development and scheduled shipment.

Estimating makes documentation accountable, in both senses of the word:

  • You can explain the time you will spend on documentation. So it allows you to plan and budget the time. Share the estimates with your manager, and you can also share responsibility for the efforts.
  • You can also be held accountable for the time you have spent. With estimates, you only will have to justify the specific difference that you ran over the plan. That’s much better than arguing about the complete time which may “seem kind of long” to your manager, though you know “that’s just how long documentation takes”…

Estimating makes documentation more transparent, in other words. It gives you and other stakeholders specific numbers to talk about ahead of time. It gives everybody more control over the documentation process.

For example, I once faced the complaint from product managers that documentation held everything up, that we could ship sooner, if only the tech writer got his act together. By introducing estimates and refining the reporting, I was able to show that it was specifically the reviewers which held up the process. Everybody took the estimated time, more or less, but reviewers delayed their tasks unduly. In fact, one late reviewer was a product manager who had voiced the complaint…

What to estimate?

You get what you measure and estimate. Or in the words of Tom DeMarco: “You can’t control what you can’t measure.”

If you estimate number of pages per day, you’ll get reams of paper. But that doesn’t guarantee that the documentation is useful and/or accurate.

If you count the number of features, options and buttons and base your estimate on that, you’ll get a thorough description of the user interface. And a customer who says, “Don’t tell me how it works, tell me how to use it.”

Apply task-oriented writing and estimate topics, instead:

  1. Look at the specifications and designs to understand what’s being developed or produced from a user’s point of view.
  2. Distill or translate what you find:
    • Identify modular concepts that users will need to know. A microwave convection combination oven can use descriptions of both concepts with their principles and different use cases.
    • Sketch out user workflows to set up and operate the product and break them down into individual procedures. That oven’s manual will probably have procedures to set it up, to thaw frozen food, to heat food (using the microwave), to bake stuff (using the convection), and to clean it.

A high-level view of the topics and their complexity allows you to make a rough estimate how long you’ll need to create useful topic-based documentation.

How to estimate?

Estimate efficiently. I once estimated a one-month project so well, I was off by two hours in the end. The problem was that it took me two days to crunch all the numbers… I can’t recommend that.

So don’t try to be 100% accurate in your estimate, if it takes you a long time to do it. Here are a few ideas to spend less time on estimates:

  • Look at past efforts: Most likely, you’ll do some reporting anyway. Use this as the basis for future estimates. Maybe you’ll find an average time you take to write a concept topic. And one time period for easy and short procedures and another for more complex ones.
  • Refine your estimates and average sizes over time: No need to get it perfectly right the first time, especially, if you start estimations on your own account. Try to run the numbers beneath the radar before you come forth with them.
  • Trust the law of averages: What extra time you need for one topic, you’ll probably save on another.
  • Trust your experience: After a while, you won’t need to sketch out individual topics. You’ll be able to take an adequate measure from looking through the spec or design.

Further reading

To learn more, check out:

Your turn

Do you estimate your efforts ahead of time? Is it worth the extra effort? How do you use the numbers to your advantage? Please leave a comment.

Index this!

An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions.

In this post, I share my best advice about building an index. And I ask for your help and opinion on a couple of details.

To make your index entries helpful, anticipate user searches. Think of it as a parallel to online search results. When building an index, think primarily of what users might want to look up and find in your documentation.

To create an index, follow these three steps:

  1. Create index entries.
  2. Build the index.
  3. Clean up your index.

1. Create index entries

  1. Scroll through your entire document and search for words and phrases that you want to appear in the index. Select only occurrences with substantial descriptions, not just mere mentions.
  2. Create an index entry, depending on your help-authoring tool or other software. Edit the entry to avoid all unnecessary words, such as articles (“a” or “the”) and prepositions (“in” or “by”, etc.).

When creating index entries, consider these issues:

  • Redundant entries, where you have several entries for the same thing, may seem wasteful and confusing. However, if users are likely to search for the word “equity” in addition to “stocks”, consider using one of the terms to refer the reader to the other entry.
  • Cross-references between index entries is a suitable compromise between usability and completeness: Of course, it is an extra step for the reader to move from the entry “Equity: see Stocks” to the “Stocks” entry. On the other hand, it is much more difficult for writers to keep both entries “Equity” and “Stocks” complete and identical over time. Which do you prefer, as a reader and as a writer: Is it okay for readers to move to a second entry? Or should the page numbers be at each entry?
  • Nested entries can help you to structure your index and alert the user to hierarchies of concepts and functions. It also cleans up your index by avoiding redundant words. Don’t have more than two levels, however. What’s your experience: Are nested entries helpful or generally confusing to readers?

2. Build the index

At any time after creating your first index entries, create and preview your index, depending on your help-authoring tool or other software.

3. Clean up the index

After you have created all index entries, rebuild and update your index. Then review the existing index for inconsistencies and go back to the index marks in the text to correct the following issues:

  • Omit double entries of the same term, but with different spelling or singular and plural.
  • Break up index entries that list more than 5 target pages. Refine index entries, for example by creating additional second-level entries for separate tasks, such as “Setting up”, “Calculating”, etc.

Optimal length and scope of an index is the result of a compromise: Make your index as long as necessary to support readers to use your documentation quickly and efficiently. And make your index as short as possible to spare yourself unnecessary work and the reader confusion.

Whether your index is too long or too short is a matter of judgement. Put yourself into the reader’s shoes once more and review your index. You may find that your index is a little too short and missing some terms that users might also look up.

Read more

Good resources for building an index are these two web pages and three books:

Your turn

Please help me out by weighing in with your experiences and opinions to the questions above. Or feel free to tell me if  I forgot anything? How do you create an index for printed documentation? Should online help also have one, or is the search enough? Please leave a comment.

Master change – with skills or attitude?

In the face of fundamental changes, skills seem to follow attitude. That’s my second conclusion from Sarah O’Keefe’s webinar about “Managing in an XML environment”. Read on for my summary of her argument and my comments. (Or see my previous post “Top strategies to embrace cost metrics” for more insights.)

Technical writers need a different skill set when moving to structured writing, topic-based authoring or an XML environment, Sarah explained. The general types of skills are the same as when writing “old style” books, such as user manuals: You still need writing skills, people skills, tool knowledge and domain knowledge. But the skills shift focus and application.

Shifting skills

Basically, Sarah argued, you need less tool knowledge and more of the other three skills – and better:

  • Writing skills focus on writing topics and their reuse. Writing topics requires more structure and better compliance to templates than book-like documentation which suffers free-form writing more easily. And topic reuse involves a lot of collaboration.
  • People skills enable increased collaboration. Colleagues may reuse, tweak and add to your topics. In fact, there’s no such thing as “your” topics, once they are subsumed into a larger collection of topics to which several colleagues contribute.
  • Tool knowledge decreases due to the separation of writing and publishing. Yes, you need to learn new tools, Sarah allowed, but that’s an initial effort. Much of the tool effort is split off into implementation and production of the documentation.
  • Domain knowledge steps in to sustain documentation quality. You can no longer hide behind the tools and improve specific parts of the documentation by layout or presentation.

Among all these changes, Sarah said, the biggest challenge is actually to come to constructive collaboration among writers. In a structured environment, the emphasis is on the process of writing and maintaining topics, not on the deliverable end product, such as a manual. Writers share responsibility for topics – which is very different from “owning a book”.

That’s why Sarah urged us not to “succumb to BOSSY, the Book Ownership System SYndrome” and to remember that “CROC is your friend” which stands for “Creating Reusable Objects and Collaborating” (somehow “CROAC” seemed a less appropriate acronym, I guess…).

Shifting attitudes

I agree with Sarah’s premise that topic-based writing requires different skills, with her analyses and her final recommendations. Yet I think the difference she describes is one of attitude rather than of skills:

  • Writing skills are different, not harder. I think it’s just as difficult to write a good, “old style” user manual as writing good topics. Writing topics seems to require more skills, because it’s new and different. I don’t think it’s actually harder, once we writers come to terms with its newness – and our resistance against it, however good reasons we may have.
  • People skills are overdue. I guess we tech writers feel the same pressure as many other professions: To collaborate, to heed stakeholders, to reach out to other teams and to connect to customers. If we notice the pressure more, it may be because we’ve worked in relative isolation. Mastering any change is much easier with a bunch of like-minded people than when you feel alone, stuck in the trenches.
  • Tool knowledge is overrated. Banking on tool knowledge isn’t the best career choice since your job hinges on a tool – and a specific version… When your tasks change, there’s the chance that your tool isn’t the best (anymore) for what you need to do. Tech writers should be really good at wrangling content (props to Scott Abel), not tools. If you distinguish methods and tools, I think you’ll find that it’s much faster to learn a new tool than to learn a new method, such as topic-based authoring.
  • Domain knowledge is second to content proficiency. While one can never have too much domain knowledge for a job, our key skill is to structure and relate that knowledge. I firmly believe that you should “always hire the better writer“, for two reasons:
    1. It helps your corporation to build up complementary skills: Your corporation probably has lots of domain specialists already – but how many really good writers does it have?
    2. In my experience it takes a year or two to become a decent domain specialist – but it takes longer than that to become a decent writer. (Though your mileage may vary…)

That’s why I come to a different conclusion. How successful we tech writers are when changing to a environment or processes depends less on our skills, but more on our attitude to them. There are at least two different ways we tech writers can regard our deliverables, our writing skills and our tool knowledge:

  • If they are our assets and define what we do, any change in environment and processes will threaten us.
  • If they are the results of previous learning, we can embrace change with the confidence that we can rise to the challenge again.

For example, when I feel I own a manual, any review, any editing has serious crisis potential already. I know what it’s like, I’ve been there… But once I feel shared reponsibility for the documentation at large, it takes on a more constructive, larger dimension, where we’re all in it together. Well, most of us, anyway… 🙂

Your turn

What determines how you face change: Your skills or your attitude? Can training and skills ensure buy-in for a new environment or processes? Or is it more important to have a self-confident, competent attitude?

Ragged-right or justified alignment?

Which alignment on the printed page is better: Ragged-right or justified? It seems that ragged-right is preferable, at least in some circumstances.

Today, I’m re-posting a piece that I first published on April 23, 2009, on the now defunct Content Wrangler site and then moved it to this blog as legacy material that was buried in the dark links of history…

I’m revisiting that post for two reasons: To my surprise, this has been one of my most popular posts in terms of search queries, so apparently this is an interesting topic. And I’ve discovered an additional argument with a twist that was new to me…

But first, let’s rewind…

Last year, I wrote:

How do you argue for the preference of ragged-right over justified alignment in print? Searching the web, I soon came across pages which mentioned research, but it was harder to actually find it.

  • The National Center on Educational Outcomes put out the NCEO Technical Report 37 which summarizes several arguments and references on the topic in “Table 3. Characteristics of Legible Type”, see the entry on “Justification”. Among them are:
    • Margaret Gregory’s and E. C. Poulton’s article “Even versus Uneven Right-hand Margins and the Rate of Comprehension in Reading”, Ergonomics, Volume 13, Issue 4, July 1970, pages 427-434. From the abstract: “… made no difference for good readers, but for the poorer readers the justified style resulted in a significantly worse performance.”
    • Steven Muncer, et al’s article “Right is Wrong: an examination of the effect of right justification on reading”, British Journal of Educational Technology, Volume 17, Issue 1, January 1986, pages 5-10. From the abstract: “… with reading material presented in right-justified format and in ‘ragged’ uneven line format, subjects performed significantly worse on right-justified material.”
    • David R. Thompson’s paper “Reading Print Media: The Effects of Justification and Column Rule on Memory”, paper presented at the Southwest Symposium, Southwest Education Council for Journalism and Mass Communication (Corpus Christi, TX, October 6-7, 1991). From the abstract: “… best score for recall was recorded in the flush left/jagged right.”
  • The UK government agency RNIB’s “Clear print guidelines” on designing printed information that is accessible to people with sight problems: “… avoid justified text as the uneven word spacing can make reading more difficult.”
  • The SEC’s “Plain English Handbook: How to create clear SEC disclosure documents” (PDF), see p. 50: “… spacing between words fluctuates from line to line, causing the eye to stop and constantly readjust.”
  • … and a thoughtful blog post by Ken Adams with an argument by Ellen Lupton, curator of contemporary design at Cooper-Hewitt National Design Museum, and author of “Thinking with Type: A Critical Guide for Designers, Writers, Editors, & Students”: “… subtle word-spacing and letter-spacing algorithms are needed to make justified text look ‘good’.”

Now I’ve found more arguments:

Karen Schriver’s book Dynamics in Document Design of 1997 is both comprehensive and excellent in explaining the motivation, the tools and the history of good document design. Be warned, however, that it deals almost exclusively with printed document design. Online design is the afterthought that takes up Appendix C, pages 506-517. (That detail right there tells you pretty much what kind of a book it is… 🙂 )

Schriver essentially argues that ragged-right vs. justified is the wrong question – imposed on us by software options, I want to add. According to Schriver, the real issue is word spacing.

Regular word spacing makes for faster reading and more accurate comprehension, in both ragged-right and justified text. Much of the software we use for writing gets word spacing in ragged-right alignment reasonably right without too much trouble. The problem with justified text is that it requires a sophisticated balance of letterspacing, word spacing and word hyphenation which much software apparently doesn’t get right automatically. Instead, it…

…creates a disturbing visual illusion known as “rivers” – paths running vertically through the text that connect the blank spaces between words on adjacent lines. (p. 270)

Here’s an illustration of rivers, from the Wikipedia article on Sentence spacing:

An example of the "river" effect in justified text

So, the bottom line is: If you have rivers in your text, consider ragged-right alignment to do your readers a favor – or invest extra time in spacing your lines nicely.

– If you know of any other arguments or sources that can help us tech writers with alignment and justification, please leave a comment!

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:

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.