Recently, at a lunchtime pow-wow with a group of friends from one of the STC chapters, a documentation group manager complained about productivity problems he was having with his junior technical writers. “They aren’t lazy,” he said, “but even when they seem to understand the material, they take forever to finish drafts for review.”
Once the writers submitted material for review, there were apologies because lists “didn’t come together” or “flowcharts took more time than expected” or “the introduction is weak…don’t read it because it’s getting rewritten.” Hearing about the problems the writers cited, and the kinds of comments and markups made during the review process, it was clear to those of us who taught college writing courses that this manager’s writers were struggling with some classic problems in their writing process.
One of the challenges of managing new writers is helping them discover and develop their writing process. Whether the new writers have just come out of school, or have recently “fallen into” the field without the benefit of much training, they often experience the same problems in planning and composing — which have their roots in how they learned to write.
The remainder of this article addresses a variety of activities – each of which can be crucial to new writers.
· The Phases of Writing
· Outlining
· Prewriting
· Composing
· Build a Library
The Phases of Writing
Let’s reflect on how we wrote while we were in school, which was driven by our teachers. We would:
1) Complete preliminary research to build the hypothesis for our paper.
2) Turn in a hypothesis statement for a teacher to grade/approve.
3) Construct an outline based upon our research.
4) Turn in the outline to the teacher for grading and comment.
5) Do some more research.
6) Write and submit a first draft.
7) Do the necessary work to complete the final draft. (Depending on how we worked, there would be several revisions (or none at all) before turning in the final draft.)
The whole process made writing seem linear, with distinct steps (which we tried to skip or condense as we got older). In reality, writing is a circular process involving prewriting, composing, revising, editing, and releasing. “Unless you are freewriting, therefore, movement through the process does not occur in a linear sequence of separate stages or in a single, undifferentiated act of ‘writing.’ Instead, progress occurs in overlapping spirals, or ‘loops.’ Within the composing phase itself, writers usually move continually through ‘micro loops’ of planning, reading, revising, and editing.”[i]
When you say the word “outline,” many of us shake as we remember some teacher whose rigidity about outlines gave us cause to hate this part of the process. For those of us who went through school without computers, we remember the hours spent typing and retyping outlines on old Brother or Smith Corona typewriters each time a change was made — sometimes choosing to exclude something from our papers because we didn’t want to retype and resubmit the outline.
With word processing applications, revising outlines became less laborious. But anyone who’s worked in these applications is familiar with their tendency to act on their own: indented paragraph styles yield unexpected results, auto numbering continues from a previous list instead of restarting, unnumbered paragraphs of supporting details require extra formatting footwork. You end up troubleshooting the formatting and lose track of the text. The result: another excuse not to outline.
The problem is that technical writing is well-served by outlining. Outlines let us work at a high level to catalogue information elements; we can get what we know down on paper without focusing too much on what we do not know. Getting too preoccupied too early in the writing process can make us so discouraged by what we don’t know, it takes us forever to begin writing a first draft.
When you’re developing online help systems or hefty manuals, outlines are effective for mapping out concepts, processes, and procedures, as well as the hierarchy in which to present them. After the composition phase begins, you can revisit and revise your outlines, letting you “zoom out” to the skeletal structure of your material to see what needs to be added or reorganized more easily than if you were working in the paragraphs, sentences, and lists of a developing piece.
Outlines also help guide follow-up conversations with subject matter experts. Sometimes writers enter these conversations knowing that information is missing, but they don’t know what or where and, therefore, don’t know what questions to ask. Inevitably, this makes them feel embarrassed or insecure about their performance. With an outline, SMEs usually can see for themselves where information is missing — and a writer can feel like they’ve saved face.
If you want to outline more but hate the tool in your word processor, there are alternatives on the shareware market. One program is Action Outline (downloadable from http://www.actionoutline.com). This program lets you focus on the content you’re trying to develop, instead of on the tool in which you’re working. The two-panel window lets you write your outline on the left, and enter supporting notes and drafts on the right. Using checkbox options in the program’s export tool, you can easily format, auto-number, and fuse together outline items and supporting text. You can also import exported files into applications such as Microsoft Word or Adobe FrameMaker when you’re ready to move ahead in your writing process.
For writers who learn or think visually, flowcharting tools might be a better fit. Programs like Microsoft Visio include flowcharting options, and the developers/engineers in your company might know of another program or have an active license for one. There are also “graphical” or “visual” outliners; two names that have been frequently recommended on writing listservs are:
The advantage of using a third-party program is that it gets around the psychology of the stuck writer. If Word or FrameMaker is where writers typically write, and is therefore the place where they’ve gotten stuck before, it’s not the place to work when they’re trying to get “unstuck.” Once they start working in a different program — neutral territory, if you will — writers often find themselves writing “in the zone” in no time.
Sometimes, outlining isn’t enough to loosen up a writer and get them started. In these cases, some playful prewriting can get words on paper where other strategies fail. Working with different types of lists, writers inevitably see their content in a different light. Even if you don’t ultimately use these elements in the final product, they do offer an effective starting point for livening up writing and revealing ways to be clear, concise, and complete.
- Top N Lists
- To-Do Lists & Checklists
- Recipes
- “Least You Need To Know” Lists
- Recommended Best Practices (written by the product developer for users)
- Common Practices (written by users for other users)
- Charts, Tables & Graphs
- Quizzes & Self-Tests[ii]
Because lists, by their very nature, force brevity, writers can put down imperative statements (e.g., “Don’t delete data from partitions until you’ve verified your last backup tape works”) and worry about filling in supporting details later. The side benefits of this writing exercise include:
- The lists whose tone and structure might be inappropriate for a reference manual can be useful additions to the user knowledgebase, or great takeaways in training classes.
- List items can be effective headings, subheadings, table titles, or figure captions.
- Lists can be expanded into short “filler” articles for newsletters that you send to users, consultants, or technicians.
When opened up to a roomful of writers over, say, a company-purchased Chinese take-out, these exercises take on a life of their own. Writers are able to share what they know with each other, and reveal humorous or alternative ways of looking at the most mundane — or the most complex — information. In a light-hearted, informal atmosphere, writers will be more comfortable about sharing information and less insecure about making mistakes. And it’s not uncommon for a team member to rise to the surface as a kind of peer mentor who can share strategies from his/her own writing process on the job or in outside activities like volunteer organizations. Once writers see through these exchanges that everyone they work with occasionally struggles with writing tasks or certain subject matter, they become less paralyzed by their own difficulties.
During the composition phase, old writing habits can appear when a writer is struggling with the material. Passive voice, long sentences, poorly constructed lists, polysyllabic words that send readers to the dictionary, headings that say little about what they’re introducing — all are symptoms of a writer who doesn’t have command of the subject and doesn’t recognize the first draft as a chance to resolve confusion.
Writers pressure themselves to get it right the first time, because the consequences of getting it wrong can be high. A user might incorrectly load a new printer cartridge, delete data from a database table, administer the wrong dosage of medicine, or incorrectly program a Mars rover to use kilometers when the original calculations were based on feet. Writers get so caught up in editing and revising in order to perfectly present their topic that they continually interrupt the composition phase; the more they try to make their first draft the only draft, the more they struggle with composition.[iii]
Teaching editing or revision strategies is not the answer here. Encouraging writers to explore and learn from other genres is. The more writers learn to play with language and work with its nuances, the more comfortable they become with the writing process and the decisions they make during it. What a writer does in the first draft may well be revised and polished in a subsequent draft, but the trick is to get the words down on paper in the first place. A writer can always revise later — and making changes isn’t any more time-consuming than sitting at your desk doing nothing while you wait for the perfect paragraph to come.
In his book UnTechnical Writing, Michael Bremer suggests that technical writers look to the following for inspiration:
- Popular science books, which convey complex information to the general reading public with enthusiasm and passion.
- Screenplays, which show how you can cut things down to what’s important/necessary without sacrificing completeness.
- Children’s books, which show how to tell stories or convey information in a shorter format with a simpler vocabulary.[iv]
Given the dry writing style often exemplified in technical writing course textbooks, the explorations suggested by Bremer may be a novel concept to the new technical writers. By even modeling what they observe elsewhere can go a long way toward loosening up a writer’s writing — and can help a team of writers decide what changes they’d like to make to their internal style guide.
Another way to loosen up writers and get words flowing onto the page is to get them to write more like real people talk (to a certain extent). When documentation reads like a textbook, users tune out (and writers and editors do, too). As Bremer notes, “Your goal is to get the information from your mind into the reader’s mind as quickly and painlessly as possible….When readers feel comfortable, they absorb more.”[v] Think about the success of the Dummies series of books; they read like you’re having a conversation with the author, and the tone is often witty and sometimes irreverent. The breadth of the Dummies catalog illustrates how often readers turn to this series when they need to learn something; anything that generates that much repeat business clearly offers something the rest of us can learn.
Build A Library
As a final note, documentation managers should consider including budget items for writing resources for their staff (beyond memberships to the STC and the IEEE’s Professional Communication Society). Two must-haves are:
- “UnTechnical Writing” by Michael Bremer
- “Secrets Of User-Seductive Documents” by William Horton (an e-book purchased and downloadable from www.horton.com)
Other possibilities include specialty newsletters that focus on editing or Web writing (among others), because they provide useful information and serve as excellent models for conveying complex information in very little space. Two examples are:
Online booksellers like Amazon.com also feature recommended reading lists from customers and reviewers, as well as “customers who bought this book also bought…” lists. Both show interesting cross-sections of technical writing resources and books from other genres. Don’t forget, too, to ask your writers — many writers invest heavily in subscriptions and books and not only would be willing to make recommendations, but might consider swapping back issues and no-longer-needed resources.
Managing new writers, and helping them develop their writing skills, requires extra time and some mentoring, both of which can be difficult to fit into a manager’s busy schedule. Instead of viewing it as a “necessary evil,” managers can view this mentoring as an opportunity to re-energize their staff, re-evaluate the existing documentation model, and develop new ways to communicate with users that also increase the documentation group’s visibility in and value to the company.
[i] Hjortshoj, Keith. “Understanding Writing Blocks. New York: Oxford University Press, 2001, page 30.
[iii] Hjortshoj, page 30.
[iv] Bremer, Michael. “UnTechnical Writing.” Concord, CA: UnTechnical Press, 1999, page 33-35.
[PRINTER FRIENDLY VERSION]
