Writing is like sorting laundry -- practical advice for tackling documentation projects

by Tom Johnson on Jan 29, 2015
categories: technical-writing

A reader recently asked,

This is sort of a beginner question, although I am not technically a beginner. I've been helping to maintain a medium sized doc set for a suite of products at a large company for over ten years. I've never written a significant document from scratch in my 10+ years as a technical writer -- I've written new topics, documented new features, and written more release notes than I can count. Now my manager expects me to author a help system for a new thin client from scratch in a few short months. The product will be high profile and I am certain I am out of my depth. I am at a loss. I'm grasping at straws, but if you can offer advice I am all ears. One option is to dive in and do the best I can. With that plan, I would love to know if you are aware of any online resources along the lines of "Help Authoring 101."

Great question. Although you've mostly been maintaining existing documentation during your career as a technical writer, I think you may find that creating docs from scratch is actually more enjoyable. When you create documentation from scratch, you don't have to play guessing games about the accuracy and origins of the content. My preferred writing mode is the blank page.

Identify the tasks

On a basic level, start by identifying the goals users have with the application. What real business tasks will users need to do? If you draw up a list of the tasks, this gives you a starting point. In general, you just explain (using numbered steps and subheadings) how users can perform each of the tasks.

Here's a good video I found yesterday that explains this approach:

Like sorting laundry

When you dig into the meat of the project, though, it gets more complicated than simply describing tasks. If documentation were a matter of simply jotting down some notes and putting them into 1-2-3 formatting, the whole scenario wouldn't feel so daunting.

After sketching out the skeleton of tasks, here's how I approach any writing problem. I have found, oddly, that my approach to writing almost exactly parallels my approach to sorting laundry.

Step 1: Gather all the laundry into one pile.

In the first step to sorting laundry, I dump all the laundry into one place, usually my bed. I have four kids, so when the laundry piles up, there's a lot of it. The laundry forms a small mountain.

It can take a while to gather it all, since much of the laundry must be collected from each of the kids' bedrooms, floors, bathroom, hampers, and more. Gathering it up, putting it in the washer, drying it, and dumping it all on the bed takes a lot of time.

When writing documentation, you'll spend time gathering a lot of information from subject matter experts, meetings, prototype demos, specs, and other places. As you gather up your research, pull the various excerpts and notes into one big file. Just copy and paste paragraphs here and there, write your own quick summaries, and pretty much create one big documentation file that contains all the information, unsorted, just like the pile of laundry on the bed. In this stage, you're just gathering all the information.

Step 2: Sort the laundry into different baskets.

The next step is to sort the laundry into different piles. I have about seven laundry baskets. I lay them on the floor side by side -- one basket for each of the kids, one for my wife, one for me, and one for towels and linens.

Now the task is to put the appropriate clothes into the right basket. This may seem easy, but trying to distinguish my eight-year-old's clothes from my ten-year-old's clothes is tricky. It requires some tedious examination that involves checking tags and asking the kids.

Likewise, in your writing project, go through your giant document of gathered information and start to break up the information into different documents/baskets. Some information will fit into clear groupings, but you may also be faced with some fuzzy categories, just as with laundry. But generally this process of dividing the mass of information into smaller docs/baskets won't be too hard.

Step 3: Fold the clothes in each basket.

Now that all the laundry is sorted into their respective baskets and the bed is cleared off, I dump out an individual basket onto the bed and sort the clothes in that basket. I separate the shirts into one pile, pants into another, socks and underwear into another, and any dresses or clothes that need hanging into another. I then fold or hang the clothes in each of their respective piles.

With documentation, you do similar sorting. Take the information and group it into different sections (shirts vs pants vs socks). Put the information that belongs in a particular section together, so you end up with 4-5 sections per document.

Once you divide the content into different sections, "fold" the content into sublists. You're not writing at this stage -- you're just making lists of the content for each section. What may have been a paragraph you copied from a spec should now be a bullet point written in your own words. Each section should have a list of bulleted points.

Step 4: Put away each person's basket into their own dresser/closet.

This is the penultimate step in the laundry process. It's time to execute. I take one of the kids' baskets into their room and start putting each of the piles (shirts, pants, etc.) into the right drawers. I hang the dresses in the right spaces in the closet. I put socks and underwear in the right places.

Similarly, with documentation, at this stage, you actually write the content for each section. Here's where you're actually composing your sentences in narrative, prose-like form. The writing task should be fairly easy since you already have an outline in each section listing the points you need to cover.

Step 5: Let each kid review the newly put away laundry.

After putting away the laundry, the kids start peering into their drawers and closets looking for clothes. This usually doesn't happen immediately but rather takes place over the next few days. The kids open a drawer and tell me that I've put Callie's pants in Lucy's drawer, or I've put one Lucy's underwear in Callie's drawer, and they laugh and tell me how dumb I am. Then they manually fix all the errors.

Similarly, with documentation, you need subject matter experts to review what you've written. Send them documents to review. They'll look through the paragraphs and task lists and tell you that some information is inaccurate, other information is missing, and so on. You'll make some edits here and there, and everyone will be happy.

Bonus steps: Add visuals

I'll stop with the laundry analogy, because this is about where it ends. Once you've got the information nailed down, you need to make the content more visual. Add screenshots, video tutorials, concept diagrams, and other illustrations to your content to make it come to life.