AP style revisited

In my last post, I said I preferred the Chicago Manual of Style to the Associated Press Stylebook and Briefing on Media Law 2013. The Chicago manual contains lots of detailed examples from different disciplines, and it is well indexed. The AP stylebook seems thin on specific examples, and finding material in the print version is difficult. But just when I thought my preferences were set in concrete, along came a supplemental handbook that cracked my resolve.

Working with Words: A Handbook for Media Writers and Editors by University of Missouri journalism professors Brian S. Brooks, James L. Pinson, and Jean Gaddy Wilson provides plenty of
detailed information on grammar, sentence structure, and journalistic style. The handbook is designed to help journalism students create engaging print, radio, television, and online
communications, but it is useful for anyone who wants to connect with readers, viewers,
or listeners.

AP style expanded and explained

The authors wrote the book because there was “no single, comprehensive resource a member of the working press could turn to” to answer questions about grammar, usage, punctuation, spelling, and common writing practices. They wrote this text to elaborate on the AP stylebook. The handbook is divided into several topics:

  • Grammar and usage
  • Punctuation and spelling
  • Style
  • Writing methods for different media

It also includes an appendix with summaries of material in the first four parts of the book,
bibliographies, and a very useful index. The inside back cover lists 20 common errors in news stories, with page references to the authors’ discussions of those errors.

What I like about this book

I prefer reading fiction to reading style guides (call me crazy), but this handbook is actually fun to read. I’m not a journalist, even though I know something about “inverted pyramid” style and the need to write simply and clearly. I am, however, an avid reader of the newspaper and,
perhaps to my discredit, a big consumer of television and online news. So I read the detailed formulae and examples on writing for different media with interest, sometimes nodding my head when I recognized a method of presenting material that seemed familiar.

I like the outside-the-box ideas for changing the rules when necessary. Reversing the traditional order of a news story, for example, can startle the reader to attention. And I like the what-not-to-do lists, which are quite lengthy. I have to admit recognizing clichés that I have used over the years – starting an article with a question, a dictionary definition, a “you might think/think again” lead (and that’s the short list). Thankfully I have never written anything that began “Yes Virginia, there is a Santa Claus.”

Finally, I find the chapters on non-print media very interesting. I have written for radio (and it was difficult), but I always wondered how one structures a television story. In the online media chapters the authors discuss what does and does not transfer from print, how to vet online sources to ensure correctness, how to layer and chunk online stories for readers who generally scan, how to edit your own copy, and how to write for social media – including blogs! I suspect that the authors will have more to say on social media and online communications, with their special ethical issues, in future editions of this book.

Divided loyalties

So now, even though I continue to be loyal to the weighty Chicago Manual of Style when it comes to technical writing, I’m beginning to think that AP style is a little more fun to use
when you aren’t bound by the conventions of specialized technical communication. And I
recommend Working with Words to anyone who wants to communicate information in a clear,
compelling way.

Note: The academic press Bedford St. Martin’s (bedfordstmartins.com) publishes Working with Words and associated print and online exercises. 

A matter of style

I recently began an editing job in a marketing communications department. The department has style standards, but when questions arise, writers use the Associated Press Stylebook and Briefing on Media Law 2013. During my time as a technical communicator, the The Chicago
Manual of Style
was my go-to style source. So I decided to do a little comparison of the AP stylebook and the Chicago manual to see which one I’d prefer to take with me if, say, I had to choose one style guide as my only reading material before running for cover during a zombie attack.

Granted, the audience for each book is different. I did a search and found a lot of discussion of actual writing rules (I’m with the University of Chicago on the serial comma by the way). The differences seem not so significant; both books demand clarity and consistency in writing no matter who the audience might be. But to me there seem to be differences in the authors’
approaches to preparing a style guide. I wanted to focus on the accessibility of information in the books.

The Associated Press Stylebook is so 21st century.

The AP stylebook is definitely an easy read. I used this guide 30 years ago when I worked briefly in public relations; then it was called a style guide and libel manual. Now, things are more complicated, and so is the guide. It still focuses usage, containing definitions and correct spelling for words from Amber Alert to website. And it still provides a guide to punctuation. But in place of the libel manual there are appendixes on news values and media law, including guidelines for social media, sports, food, fashion, and business; a guide to writing stories for broadcast; and a guide to using interactive graphics in news stories.

I like the casual nature of discourse and the “everyman” approach used in the AP guide. In a world of mass electronic communication and social media (including participatory wikis), all writing – including technical documentation – is casual in tone and style.

I find the AP guide simple and easy to use. The usage section consists of an alphabetical list of terms, so it is very easy to find without an index. And that’s a good thing, because I couldn’t find an index in the AP guide. The best way to navigate this guide might be online using the search function.

Get all the specifics in the Chicago Manual of Style.

The Chicago manual is detailed, with many examples from many different academic disciplines. I can usually spot an example related to the topic of the text I am editing, no matter how
obscure that topic may be. The index is exceptionally detailed, so I can find just about any information I’m looking for. But index use is hindered, in my opinion, by the military numbering system used for headings in the Chicago manual. The numbering system and references to numbered headings in the index make finding information pretty frustrating. Pre-electronic everything, technical communicators annotated their print copies of this guide to find often-looked-up topics easily. I have heard of senior editors handing down their treasured annotated copies of this manual to their favorite junior editors upon retirement!

I was mulling over the index issue when it occurred to me that indexes seem to be on the road to extinction, perhaps because you can always buy a searchable version of any book. In fact, you can get an online subscription to most style guides. Electronic subscriptions are useful
because style is not static, and it becomes tiresome and expensive to buy new versions of these sometimes-bulky documents every time they are revised to reflect changes in language and culture.

I can’t resist playing it safe.

Despite its drawbacks I’d probably choose the academic Chicago Manual of Style over the hip AP guidebook. Why? The Chicago manual covers many different disciplines, it is detailed, and it is well indexed. Most importantly, or maybe most foolishly, I like it because I’m accustomed to it.

I recently bought an online subscription to the Chicago manual. But I couldn’t resist buying
another print copy too so I’d have the latest and greatest edition on hand in case of zombie
attack and subsequent loss of Internet connection. Better safe than sorry.

Love many, trust few: The life of Anna Safley Houston

Last summer I took a temporary job as manager of the Houston Museum of Decorative Arts. No, I didn’t move to Houston! This Chattanooga, Tennessee museum contains Victorian art and antiques collected by Mrs. Anna Safley Houston.

When I began the job I was new to the museum. A perpetual open house visitor, I was very interested in the Victorian home that houses the collections. But over time, my interest focused on the collections. What at first seemed to be an old house filled with Victorian fru fru quickly became a fascinating window into the Victorian mind. I can attest from experience that a visit to this museum can send one scurrying to one’s parents’ basement to unearth treasures ranging from ceramic piano babies to marked milk glass.

The life of a collector

For sale in the museum is journalist Tom Williams’ biography Always Paddle Your Own Canoe: The Life, Legend and Legacy of Anna Safley Houston. The book’s title comes from her childhood autograph book in which a friend says: “Love many, trust few/And always paddle your own canoe.”

To say that this independent Victorian woman always paddled her own canoe is an understatement. Anna Safley Houston could fell the tree, mold it into a canoe, and fashion the oar before she ever launched the canoe.

She was born Anna May Safley in 1876, about the time that art glass made an appearance in American homes. The oldest of 11 children, she was put in charge of her siblings when her mother died. At age 15, tired of caring for her brothers and sisters, she set out on her own to see the world. Among her early jobs:

  • Buyer for Marshall Field in Chicago
  • Member of the travelling “Sullivan Sisters,” a troupe of women who groomed their hair in public to sell hair tonic
  • Milliner
  • Dress maker
  • Antiques dealer

Never widowed, Anna Safley probably married nine or ten times. Her first marriage produced two children, both of whom died in infancy. During the second pregnancy, her husband left her and, when she asked her family for shelter, they declined because it was unseemly to harbor a pregnant woman with no husband. She never forgave the family for the slight: At her death she left nothing to her siblings and instead left everything to the museum that bears her name.

Anna moved to Chattanooga with her second husband, who failed to mention that he had a venereal disease until she had been infected and who eventually absconded with at least some of her money. In Chattanooga she married many men several years her junior, but James W. Houston seemed to have been her favorite. He lasted 16 years, and she retained his name when she divorced subsequent husbands.

After the Great Depression, Anna went without food and healthcare to avoid selling anything from her collection. To evade creditors, she built by her own hand a barn-like warehouse where she lived with her dog and her glittering glass treasures. At her death in 1951, the warehouse contained over 50 collections, including corner cupboards, sugar chests, guns, ceramics, and glass. In the glass collection were 15,000 pitchers. Today, the glass housed in the Houston Museum is considered one of the finest collections in the world.

The mystery that was Mrs. Houston

In Paddle Your Own Canoe, Williams mentions several mysteries surrounding Mrs. Houston. Was she a beautiful clotheshorse or a disheveled street person? Where did she get the money to buy her collections and how did she hang on to them? And why did she take on all those husbands?

Legend has it that Anna walked the streets of Chattanooga looking like a modern-day bag lady, but that she dressed to the nines for the antique buying trips that took her to every state in the union as well as Mexico and Canada. As for funds for her purchases, that mystery is likely to remain. There is no evidence that her husbands brought money to the marriages. Her early purchases were from country folk who may not have known the value of their property, and wealthy customers could have bankrolled some of her purchases. She occasionally refinanced her millinery business and her rental properties. And perhaps there was a little bit of cheating going on as well. For example, she often had purchases shipped COD and then haggled over the price with the shipping company.

The husband question is another mystery not easily solved. With Mr. Houston she expressed an interest in trying to have children, and that may have been a factor in some early marriages. Some theories:

  • As a successful business woman and collector, Anna may have been trying to get one marriage right in order to satisfy her urge to be successful at everything.
  • Marriage represents family, connection, stability, and security. Anna seemed to be lacking all those things, and marriage may have been an expression of her need for human connection.
  • Anna may have been a “marriage addict”: Marriage may have been an extension of her obsessive urge to collect.
  • Later marriages may have failed because older couples are often less adaptable than younger couples.
  • Sometimes people marry more often because they are asked more often. Anna may have accepted every proposal that came her way.

The Houston Museum of Decorative Arts

If being a compulsive collector was Anna’s flaw, it was certainly Chattanooga’s gain. The museum on High Street in the thriving Museum Hill neighborhood is well worth a tour. A visit to the museum website at www.thehoustonmuseum.org is fascinating, but a docent-led tour of the collection can make an art-glass aficionado of anyone.

Technical communication and Millennial madness

The Millennial generation born to baby boomers in the 80s and 90s came of age in the 2000s. This swell in the population now represents a big portion of the labor pool; by 2020 Millennials will make up 46% of the work force. Because of their size and their distinctive buying, learning, and work habits, this generation is the subject of much discussion among marketers, educators, and personnel managers. Recently I did a little thinking about how to communicate with Millennials about technical topics.

Characteristics of Millennials

Self-confident. Some writers criticize Millennials as over confident, with a sense of entitlement instilled by “helicopter parents” who encouraged them to feel good about themselves even when praise was not earned. But there is merit in confidently approaching a task (or a document, a help system, or a user interface) with the assumption that you have the wherewithal to accomplish it.

Wired. Millennials are “digital natives,” and they’re savvy with social media. They use smart phones. They are expert gamers.

Social. According to Susan M. Heathfield in an About.com article, “Millennials are the most connected generation in history and will network right out of their current workplace if these needs are not met.” They like working on teams. They make an effort to seek peer approval before making decisions. They like to talk. They are socially conscious and civic minded.

Lifelong learners. Millennials expect to learn new things as part of their everyday work and personal interaction. Recently I asked a Millennial what he didn’t like about his job. He hesitated a moment, then said sadly “I’m not learning anything.” For Millennials, even ads need to teach something.

Scanners. Millennials are “scanners” who can take in a lot of visual information at once – they believe themselves to be true multitaskers.

Value work/life balance. They don’t want to spend all their time struggling over their work.

Penny pinchers. Most surprising to me, Millennials are frugal. Their salaries are typically lower than those of their predecessors. To purchase high-ticket items (like electronics) and more education, they scrimp and save. Wired and big on learning, they have perfected the art of comparison-shopping. They join car-sharing organizations to avoiding buying cars. They’re socially conscious so they demand green products and packaging.

How to engage Millennials

Common advice to those who manage, teach, and sell to Millennials:

  • Provide structure
  • Emphasize teamwork
  • Use their electronic literacy
  • Change assignments or give them multiple assignments
  • Make the workplace, learning experience, or ad campaign fun

How to communicate technical info to Millennials

Gamify. A leading proponent for gamification in technical communication is Oracle’s Marta Rauch. Rauch says that gamification “uses game techniques in non-game situations to motivate people and drive behavior.” Technical communicators can manage user interfaces and assistance for gamified products. And we can gamify our own communication products by providing goals, rules, feedback, and rewards.

I attended a session on winners in the International STC publications competition, and one winning entry was a training video for a fast-food restaurant. Trainees play a fun game, receive rewards and positive feedback, and generally learn how to do their jobs in a way that would be fun for anyone, no matter what generation you happen to be born into.

Note: Follow Marta Rauch to learn more about gamification and other cool things at
martarauch.wordpress.com.

Emphasize structure: Helicopter parenting created a generation of people accustomed to structure in their lives. Establish the purpose, learning goals, and structure of your documentation product and then test users to be sure that they have met expectations.

Make your documentation accessible at a glance: If you’re using “slow” media, remember the way Millennials read. They scan, taking in lots of visual information at once.

  • Make online information uncluttered and easy to view
  • Properly index print documents
  • Tag and bookmark online documents
  • Provide logical navigation tools in help systems
  • Label text, tables, and graphics with meaningful headings and captions

Listen to your users. Millennials are accustomed to talking and being listened to. Mine wikis, message boards, and social media sites for information. Seek feedback through social media and focus groups to take advantage of Millennials’ social nature.

Spruce up your writing style. Be direct, pointed, spare, and casual. Ideal strings of text in a gamified product, says Rauch, “are the length of a tweet.”

What’s good for Millennials is good for everyone

These are just a few ideas for effective communication to Millennials, and they work well for everyone. What trainee would prefer dry pre- and post-tests to a fun game? Who among us has not given up on the manual and turned to the message boards for answers to what seems like easy questions? Heck, I often skim the novels I read for fun, especially when the writing is verbose; I’m unlikely to read every word of a technical manual. And whether you are a Baby Boomer or a baby, you’re probably acquainted with electronic communication. Even my
Greatest Generation dad reads books on his trusty iPad.

Front yard greeting card

In The Language of Flowers by Vanessa Diffenbaugh, the protagonist Victoria researches the meanings that Victorian lovers assigned to the flowers they sent. Victoria comes up with her own list of flowers and their meanings. After reading the book, I wondered what the flowers in my yard say to my friends and family. I decided to do a little catalog of the flowers that greet visitors when they come to my front door.

At the curb

Several years ago I set out to plant a garden between the sidewalk and the curb in front of my house. I started digging out sod laid several years earlier when the house was built. The process was difficult because of the green plastic mesh used to put the sod in place. I searched for what the heck that stuff is and found that it lives forever, tiny animals can get tangled in it, and if you plow it under to make a garden, your garden might yield produce laced with green mesh. Supposedly this stuff is biodegradable but I suspect it will not degrade in my lifetime.

Pulling that mesh out of the soil is very difficult, but I did it to the best of my ability, filled in with store-bought dirt, and planted. While I was digging in the Tennessee chert and plastic, my neighbor cautioned me to stop. “This is a utility easement!” she exclaimed, “The city or a utility company could dig it up any time! It will be ugly in the winter when your flowers die! You’ll have to water it all the time!” True. I planted anyway.

I planted what I knew after living 20 years in New Mexico: Russian sage, which is drought tolerant and hard to kill. I also put in some coreopsis because they were pretty. Lucky me – For a couple of years we had minimal rain, and sometimes my curbside flowers were the only sign of life around. The Victorian meaning of sage is “good health and long life.” Coreopsis is “always cheerful.” So my front curb is a wish for good health and good cheer. I hope the mail carrier approves.

Russian sage and coreopsis  in my curbside garden

Russian sage and coreopsis in my curbside garden

Here's what the mail carrier sees on a rainy spring day

Here’s what the mail carrier sees on a rainy spring day

Beside the front walk

On one side of the front walkway I had a little slice of grass that I quickly converted to a bed. In it are roses, a Christmas camellia that blooms red in winter, some spunky stella de oro day lilies, and creeping jenny ground cover. Also embedded in the creeping jenny by accident is setcreasea, commonly called purple heart wandering Jew.

Here’s where my visitors run into trouble, and I’m not necessarily talking about the slightly mental dog that lurks behind my front door waiting to defend me from anyone who is, well, not me. This front bed is a tangle of contradictions. The camellia means “my destiny is in your hands” – quite a burden for someone just ambling up the front walkway.

The coquettes

The coquettes

A day lily symbolizes “coquetry.” In some books lilies symbolize “majesty,” but I think the stubby stella de oros are more coquettish than majestic. The red rose symbolizes love, but the beautifully fragrant yellow rose means “infidelity”! I couldn’t find any symbolism in the ground cover, but I did discover that the wandering Jew is so named because it wanders from where you planted it and thrives despite little sustenance, just as the Jewish People have adapted to many different environments around the world.

On the porch

"That creepy head" with asparagus fern

“That creepy head” with asparagus fern

On the front porch are seasonal plants – begonias, red geraniums, and an asparagus fern in a pot that looks like a head. (My daughter calls it “that creepy head” but I love it.) I did a little research on the asparagus fern and it is, as it turns out, not fern but an herb in the lily family.

In the language of flowers begonias suggest “caution” – a message I try to heed by removing the dog from the house before visitors come in. At gardenguides.com, horticulturist Elizabeth Ginsburg says: “In the language of flowers, scarlet geraniums have a meaning that relates to either comfort or stupidity. However, the meaning assigned to any geranium, without reference to color, is more promising. These geraniums reflect gentility and esteem.” I would really prefer to think of my front porch as genteel rather than stupid.

If I only had a plan

I really did not set out to give any meaning to my front yard – I just plopped in what I liked and hoped it would grow. They say you should plot out your garden on graph paper – you’ll be sorry when you plant tall things in front of short things or things that spread choke out things that don’t. Without a plan I have lost plants. Maybe I planted them in the wrong place, maybe I overwatered, or maybe I got them on the almost-dead aisle at Lowe’s and couldn’t revive them. Elephant ears disappeared for years at a time and then one spring after a warm winter they came back. Azaleas planted in full sun died a slow and painful death. Trumpet trees grew tall and stately year after year but almost never bothered to flower.

New peony, the future of my garden

New peony, the future of my garden

Recently I planted a new peony bush on one side of my front steps. A peony could mean “anger” or it could mean “good health.” Next spring I think it will be another fragrant reminder of the contradiction that is my front yard greeting card.

Flower power

Bud emerges into hostile world

I read The Language of Flowers by Vanessa Diffenbaugh because I was interested in gardening and the ways in which Victorian lovers communicated through gifts of flowers. But the novel gave me insight into more than the secret messages that a garden emits. It taught me what it must be like to parent oneself as an adult emerging from the foster care system – a system I am tangentially a part of.

I’m a volunteer on my county court’s foster-care review board. Every month my panel reviews cases of children in foster care, talking with parents, caseworkers, attorneys, and children. Each month we report on these cases to the juvenile court judge. Many cases involve children who have grown up in the system. Never adopted, these children “age out” and become independent adults at 18.

Our panel often wonders about our children’s preparation for the adult world. Will they receive the training they need to get a job? Do they know how to parent the children they have or children yet to be? We are painfully aware that from an early age, many children in the system raise themselves and sometimes care for their own debilitated parents. Despite independent living training offered to teens in the system, the situation feels hopeless to me. I have a sense that the children who age out of the system can easily become homeless, criminal, or even mentally ill. And there is not a lot I can do about it.

Flower blooms despite setbacks

In the story, Victoria has grown up in the foster-care system, developing an adversarial relationship with the caseworker who has been her only constant in 18 years and with the many foster parents who have deprived her of nourishment in the figurative and sometimes literal sense. Only one foster parent, Elizabeth, loved Victoria, but at a crucial moment she failed as a parent, and the child was plunged back into the system. At 18 Victoria emerges from a group home stunted, guilt ridden, and unable to trust anyone, not even herself.

Victoria ages out of the foster care system with only the Dictionary of Flowers and Peterson Field Guide to Pacific States Wildflowers to guide her. Her only skill is knowledge of the Victorian language of flowers taught to her long ago by Elizabeth. She uses her skill to finagle a position with a florist and to communicate with those people she comes to love. By the end of the novel she is slowly learning how to love others and trust herself.

The author, herself a foster parent, gives us a glimpse into life for those who age out of the system. Having raised herself with not much help from adults, Victoria possesses an Artful Dodger’s sense of survival. She knows how to steal food and hide it on her person, on the presumption that she may not eat for a long time. She attempts to live in a San Francisco park but soon realizes the personal risk and finds a safe (not necessarily comfortable) place to live. A self-taught reader, she learns how to use what she knows to make a good living. Throughout the story, though, she shields herself from human interaction, finding solace only in flowers.

Bloom recovers from blight

Recently the Tennessee Commission on Children and Youth issued a report on the peril that “toxic stress” puts on children who have experienced abuse, poverty, hunger, and abandonment in the foster care system. The report suggests that children who age out of the system experience life-long physical and mental problems. Older children in foster care sometimes have children of their own, and the cycle is perpetuated.

Vanessa Diffenbaugh, though, thinks that cycle can be broken, that abandoned children can make a successful transition into the adult world after emancipation. And she put her money where her beliefs lie, using earnings from The Language of Flowers to establish the Camellia Network (camellia network.org). This organization helps young people transition from foster care to the world of education and work. Camellia means “my destiny is in your hands.”
Diffenbaugh believes that if society stops thinking of recently emancipated foster children as “those kids” and starts thinking of them as “our kids,” such children can become viable members of society.

Flower power

Victoria learns that just as people are complex, so is the Victorian language of flowers – each flower can communicate multiple emotions. She creates a dictionary of flowers, poring over old books on the subject, determining what each flower means to her. Diffenbaugh says she did the same thing to come up with Victoria’s flower dictionary, which she prints at the end of the book.

This novel gives new meaning to the term “Flower Power.” No matter what their meaning, flowers give Victoria a way to emerge into adulthood, a way to connect with others in meaningful relationships, and a way to forgive herself and others.

In future blogs I will discuss the meaning of the flowers in my garden. I probably won’t experience significant self-discovery like Victoria does, but I will have a way of sharing the power of the flower.

Remembering Civil War Chattanooga

Our book club has read a few books about Chattanoogans. One such book was the memoir of Thomas Hooke McCallie, a Presbyterian minister and patriarch of a prominent Chattanooga family. Our club discussed the book with THM’s grandson, physician David McCallie, who edited and annotated the book. I wrote the following review for the Rivermont Presbyterian Church newsletter.

In THM: A Memoir, Thomas Hooke McCallie (THM) chronicles the McCallie family’s immigration from the lowlands of Scotland and move to Chattanooga, and her recounts his own experience of the Civil War and Reconstruction.

THM was anti-slavery and anti-secessionist, but he believed that secessionist states should not be forced to return to the Union. His unorthodox views on slavery were shaped in part by his religious experience. A player in a great religious awakening that swept across America before the Civil War, THM attended Union Theological Seminary in New York, where he heard in person such imminent speakers as Henry Ward Beecher and Oliver Wendell Holmes. He also gained a new perspective on slavery from his fellow seminarians, who sought out Southerners to “assault with argument” about slavery.

THM and his family stayed in Chattanooga during the war, witnessing battle and enduring the siege of Chattanooga. The memoir offers much comment on the war, including the character of each army (Confederates were polite but not inclined to hard work, Union soldiers rude and uncouth but disciplined and hard working). In the Presbyterian Church, he preached sermons to locals, Confederate officers, and Union officers—on different Sundays, of course.

The memoir reflects the role of the church in American society during the 19th century: Faith sustained family and community and helped people deal with the very real presence of death. In one moving passage THM describes his prayers for the recovery of his dying child and his uncertainty over whether those prayers were at odds with Christ’s calling the child home. Though THM emphasizes the joy of salvation, he never turns away from the internal questioning that is central to the Christian experience.

Simplifying online help

Dear Style Master: How can I reorganize my thousand-topic online help system supporting a business software application? Customers are having trouble navigating the system to find out how to use the software to do their jobs!

– Everything but the Kitchen Sink

Dear Sink: It’s great that you know what customers think about your system. Often we labor over product documentation, release it, and never know the value of our work to customers. As far as reorganizing, I suggest taking a cue from Thoreau: Simplify, simplify, simplify.

Start by creating workflow diagrams for each task customers will perform. In each diagram, list topics in the order in which you would use them to accomplish a task. Be sure that every topic in the system is listed in at least one workflow diagram. Hint: If a topic doesn’t fit into one of the workflow diagrams, maybe you can delete it from the system.

Next, look at the diagrams and see if there are topics you can eliminate, being careful not to eliminate a topic critical to multiple tasks. For example, identify background, reference, and detailed instructional material that you can move to another document, like a user guide. You can always link to the user guide from the help system so that the reader can find additional information easily. You might also be able to delete unnecessary graphics and confusing cross-references. If you are in doubt about cutting specific topics, ask an editor, reviewer, or peer to weigh in on whether or not to remove the items from the system.

Finally, review the existing system topic by topic. Edit wordy text and eliminate the obvious – phrases like “Respond to the ‘Are you sure?’ prompt” may not really be necessary.

After you revise and release your help system, continue your quest to know how customers view your system, through usability testing, standard customer feedback tools, or maybe a friendly phone call.

The joy of outlining

Whether you’re writing a white paper, a set of instructions, help for a mobile app, or a simple blog post, your first step is planning. And planning means analyzing your audience, defining a purpose, gathering information, and developing a preliminary outline.

Why create an outline

Why bother with an outline when you have all the information you need tucked safely away in your head? An outline ensures that some of that extensive information in your head isn’t inadvertently left there, never to make its way onto the page or screen. It helps you keep on point, so that you don’t distract readers with nonessential information. It helps you stay on task despite disruptions and distractions.

An outline is a map you can use as you to develop, revise, and test your ideas with reviewers. It can make the writing experience straightforward. And if you take pleasure in efficiency, an outline can help make the writing experience downright fun.

Choose your outline type

To prepare a detailed outline, sort the information you have gathered into topics of relatively equal importance, then identify subtopics. For short documents like quick references or online help topics, you might choose an informal outline, which can be a simple numbered list of topics. For example, if your task is to write a quick reference card on preparing for a laboratory procedure, you might use the following informal outline:

1. Draw blood.

2. Store blood.

3. Dilute samples.

4. Purify samples.

5. Clean prep station.

For more complex documents, choose a formal topic or sentence outline. A topic outline uses key words, and it includes subtopics. A sentence outline develops topics using complete sentences. For most documents, a topic outline provides an adequate guide. But if you are writing a lengthy document – say a chapter or section in a book – consider writing a sentence outline that provides specific details.

Example topic outline on outlining

I.    Why an outline is important

A. Provides a map to follow as you write

B. Makes sure relevant information not dropped

C. Keeps extraneous information out

II.    Types of outlines

A. Informal numbered

B. Topic

C. Sentence

D. When to use each type

III.   Drafting a document using an outline

Note: Headings and subheadings stand for divisions of information, and a division means that there are at least two parts. So, a single subhead – “A” for example – cannot exist without a second subhead, “B.”

Draft the document

Expect to change the document’s structure as you write, even if you’re using a detailed outline. What looked simple in the outline may be convoluted in the first draft, so you create some new topics as you’re writing. Or, what you planned as a major section may contain very little information, so you opt to subordinate that information in another section.

The outline is a guideline, not a rule, and you’re allowed to change your mind as you write. In my example topic outline on outlining, the final subtopic under “Types of outline” is “When to use each type.” But when I wrote the blog post, I found it easier to incorporate a discussion of when to use each type of outline when I defined the type. Also, I thought of a new topic on how to use an outline when you are preparing a revision for publication, so I added it as a tip at the end of the post.

Evaluate document structure

After you have completed a good draft, reevaluate the document’s structure. Is the flow of ideas logical? Is the text coherent and complete? If you have a table of contents, you have a quick way to evaluate overall logic before you revise and edit what you have written. Any initial headings you have used in the document provide another sort of map to your document’s structure. You’re looking at general structure, not specific text. Reorganize any parts of the text necessary before you refine the document in the next draft.

A tip on revisions

If you’re writing product documentation, you probably have to update print and online documents to accommodate product updates. Sometimes there is a need to restructure before you add new content. Try outlining the original to see if you can find logical flaws, and revise the outline to correct the flaws. Then, reorganize the old text and add new content using your new outline. Using an outline to correct flaws in the original can be a source of joy not only to the writer but also to the reader who no longer has to endure a difficult-to-follow document.

What it means to be free

Memorial Day musings

Recently I watched PBS documentary Death and the Civil War, based on Drew Gilpin Faust’s book The Republic of Suffering. I learned at last why there are so many confederate cemeteries throughout the South. National cemeteries did not honor confederate dead, so survivors, particularly women, formed organizations to bury and honor their dead. After World War I, localized memorials became an inclusive, national holiday, Memorial Day. Somehow, despite lingering divisions caused by civil strife, our nation can come together to honor all war dead.

Last month our book club read the novel Freeman, by Leonard Pitts. It seems to me that in this novel Pitts explores the ways in which a culture can build community, even in the face of brutality, hatred, and death. This well researched book is not all about war, but rather its aftermath. Pitts focuses on the effect of sudden emancipation on individuals and communities. He presents us with the many different ways that former slaves, former slave owners, and northern abolitionists understood – and misunderstood – the concept of freedom.

The cost of freedom

Sam Freeman is looking for his wife, Tilda, after 15 years of separation. Sam escapes slavery and survives service in the Union army. As soon as the war is over, he sets out to find Tilda, whom he had left behind, walking thousands of miles through a dangerous Southern landscape. The odds are against him. Tilda has been sold to a brutal owner who cannot comprehend the loss of his property to emancipation. After having been terrorized for many years, Tilda is unable to leave her former master, and she reluctantly follows him west to become the slave of a militia intent on rekindling the war.

Another character in the book, Prudence Cafferty Kent, is a headstrong abolitionist who celebrates union victory by travelling from Boston to Mississippi to establish a school for former slaves, with disastrous results. She is left with a profound sense of guilt that gives her purpose, just as Sam’s guilt at abandoning Tilda to escape slavery gives him the will to continue the search for Tilda despite tremendous odds against finding her.

For both white and black members of Southern communities, freedom was a difficult concept to grasp. In an NPR interview Pitts comments: “Freedom was not just this automatic thing that came because somebody came and read a notice that said you all are free now.” Former slaves often had little idea of where to go when they were set free. White Southerners viewed slaves as property, and they did not part with their investment lightly. White and black Northerners grossly underestimated these slave owners’ desperation to preserve their former way of life.

Freedom to behave imprudently

In our discussion, most readers felt that Sam and Prudence both jumped the gun by setting south so soon after the war ended. Prudence in particular seemed naive and rash, and her actions during the course of the book caused great harm and even death in the African American community she tried to help. There is a lot of discussion of guilt in this book. Both Prudence and Sam take on mantles of shame for their rash actions, and both have to learn that they do not bear the burden of guilt for slavery, or for the death and destruction caused by whites who could not bear to see their way of life change.

This very powerful novel portrays a reality about the aftermath of Civil War that I hadn’t really considered carefully until now. For many years, so many people roamed the American landscape seeking to reunite with their families. I had to ask myself what I would endure to be reunited with my family – would I have had the fortitude to face the danger that Sam and others faced as they sought to mend ties long broken?

Freedom in a war-torn world

Leonard Pitts is a Pulitzer Prize winning Miami Herald columnist, but I think he is a novelist at heart. I’m impressed with his exploration of the themes of guilt, responsibility, and endurance, and with his development of characters that readers really care about – even if those characters, like us, are sometimes reckless and unwise.

We have read several novels set during the Civil War, including the provocative The Known World by Edward P. Jones, a book that explores the idea of slaves owning slaves, and Widow of the South, Robert Hicks’ narrative of the true story of a confederate widow in Franklin, Tennessee. Freeman offers up yet another perspective on the meaning of freedom in a war-torn world.