There are times you don’t know what to write or where to begin. Writing is rarely an unstoppable gush of words. Sometimes it’s a hard job. A few outings on the water under sail taught me a lesson that works for composition.

Sailboats all have personalities and preferences. You have to listen to what the boat’s telling you if you want the most out of available wind.

Most importantly, if what you’re doing on a boat is hard you’re doing it the wrong way. Sailboats were launched before the Great Pyramids spiked property values in Giza. We’ve had a while to refine the business of sail power. Generally, the right way is the easy way.

The same thing is true in writing, at least to a degree. You’ll never see words drift across the screen like boats before the wind, but you can maximize what you get for your efforts.

If writing is too hard, you’re doing it the wrong way. Here are some of my tools for turning a blank word processing document into a user guide when the words won’t write themselves.

There are a couple of things you’ll need before you start writing.

First, you need to understand the assignment. If not, interview the boss, client, or consumer. Don’t try to be a mindreader. Define the goal. Don’t forget to define the audience, too.

You should understand your objectives. Paraphrasing Steve Martin’s insights in his movie, The Jerk, you need to know your purpose. Are you writing pre-sales information? If you’re writing a user guide it may need to serve both as tutorial and reference. Part or all of your assignment may be narrative, or you may have both narrative and an inventory of “man” pages.

What you’re writing sets your style.

Understanding the assignment is the easiest step in the process. Next up, you may need to do some homework.

You have to understand what you’re documenting at (or better than) the level your audience seeks. Close those gaps with study and more interviews. Don’t be uninformed. Unless you’re writing incomprehensible assembly instructions for bargain furniture, you’ll need to understand the product. A little awareness might even improve life on Earth there, too.

Along with how it operates, get a handle on what end-users will do with the product.

With this step comes something many writers think they hate. Outlines.

It’s a shame outlines have such a crummy reputation. Part of that comes from how outlining is often practiced.

A deep hierarchical list of broad strokes in main topics and details in subtopics easily degrades into a taxonomy. In fact, Harvard outline format is better for categorizing information than for mapping the linear flow of a work.

Start with the easy stuff first. Make notes. Lots of little notes. You could organize them in a Harvard hierarchy, but Microsoft OneNote or a wiki would be a far better choice. Categorize and cross reference. Build your own little knowledge base. Cite references in the developers’ wiki.

Get control over source knowledge.

At this point, newfound familiarity with the product may cause your document’s structure to emerge.

If not, you need a ghostwriter. A real ghost.

Summon the spirit of Reader yet to Come. Close your eyes and ask Reader of the Future what he expects and what he needs to know.

Write that.

But don’t spend a month writing a 50 page user guide, not yet. You’d spend another month fixing 50 pages.

Instead, write your 50 pages in an hour or three. Sort of.

Write an outline. The topics should have brief notes. Do not allow your outline more than one or two levels. After all, your reader isn’t going to start a chapter and jump to a subroutine before continuing. Produce a linear map for linear work.

I think of this more as a storyboard than an outline.

Consider writing a glossary even if the finished work won’t include one.

Developers may use terms with multiple meanings. There are, for instance, nuances in the meaning of words like virtual and logical. If a developer tells you about a virtual disk, is he talking about something in the cloud, a logical partition of a local device, or an alias for a physical disk? You’re hired to slay questions like that. Make sure you have the lingo down so you can make it clear to Reader yet to Come.

Now, finally, craft your document with easy authority.

Does any of this actually work? I’ll accept any decision the court delivers. In this case, I started with a empty Markdown document, jotted a few notes in a Devonthink database, wrote a quick one-level outline, and crested 800 words somewhere in the last paragraph or two.

Study, think, write, edit. Repeat as necessary. It works.

Thanks for dropping by, it’s nice to see you. If you need a Python developer or a technical writer, please drop me a line. The Get in touch! link at the top of this page will establish contact, or email me via carl@carlhaddick.com.

Samples of Python and technical writing can be found on this site. A link at the end of every Python article here downloads a zip file with Python source and a nice PDF document.

I’m also available on LinkedIn at https://www.linkedin.com/in/carl-haddick/.