Even if you don’t enjoy writing and have no intentions of becoming a professional tech writer, chances are you’ll have to draft reports, mailing list updates, or technical articles at some point in your career. With a few practical tips in mind—along with solid writing advice from Stephen King—you can improve your writing before you start writing. And, with proper planning, you can easily repurpose your content for multiple audiences.

Before we dive into the writing part, let’s assume you know what you are writing about and why you are writing. For example, you may be writing to:

• let your community know about a bug fix or security update;
• provide a project status update to a manager;
• tell developers about a new process for submitting patches;
• or to inform the press about the latest software release.

When you know what you’re writing about and your purpose for writing it, you need to understand your audience.

Who is your reader?

Before you start writing, step back and make sure you’ve defined your audience. Broadly speaking, you can lump your readers into three categories: lay, managerial, and experts. On Colorado Statue University’s open-access learning environment, the Writing Studio, Michel Muraski explains the three categories of audience:

The lay audience has no special or expert knowledge. They connect with the human interest aspect of articles. They usually need background information; they expect more definition and description; and they may want attractive graphics or visuals.

The managerial audience may or may not have more knowledge than the lay audience about the subject, but they need knowledge so they can make a decision about the issue. Any background information, facts, or statistics needed to make a decision should be highlighted.

The experts may be the most demanding audience in terms of knowledge, presentation, and graphics or visuals. … For the “expert” audience, … style and vocabulary may be specialized or technical, source citations are reliable and up-to-date, and documentation is accurate.

If tech journalists are the readers you’re supposed to reach, and you don’t have experienced PR teammates taking the lead, hold the presses. Read The Care and Feeding of the Press. Then read it again. If tech journalists are the only readers you’re trying to reach, The Care and Feeding of the Press has you covered. Otherwise, read on.

Opensource.com readers, for example, can be lay persons, managers, or experts. We can assume that our readers have an interest in open source software, communities, or methodologies, but we cannot assume that they are all experienced developers. If we have an article that mentions microservices, for example, we shouldn’t assume that all readers will know what that means, so we need to provide a definition or link to a resource. On the other hand, we don’t need to explain documentation for anyone reading an article called When does your documentation need screenshots?, because we can assume only readers who write or have an interest in documentation will read it. (For great advice on writing project documentation, read RTFM? How to write a manual worth reading.)

Stephen King on writing

You’ve defined your audience, but don’t start writing yet. Instead, grab a cup of coffee or a snack, and start reading.

Because I’ve been thinking about writing fiction, I’ve been reading lots of novels in my spare time. Last summer, I also read On Writing: A Memoir on the Craft, by Stephen King. Although his book is about writing fiction, many of his observations fit technical writing, too. To be a good tech writer, you’ll need to read technical content.

1. Good writing requires reading

If you want to be a writer, you must do two things above all others: read a lot and write a lot. There’s no way around these two things that I’m aware of, no shortcut. ~ Stephen King

Sure, you can write only when you have to, but expect it to be a struggle—perhaps even torturous—every time. And yes, plenty of writers aren’t big on reading, but they aren’t generally good writers, and what they write isn’t necessarily worth reading.

If you’ve been given a writing assignment, be clear on the expectations. Reading examples will help. For instance, if your manager wants a project status update, reading an example update or a list of what information to include will help you meet expectations. If you are expected to contribute an event report to the company blog, read previous reports on the company blog or similar sites. Before writing an article for a tech publication, read several similar articles to get an idea of what the editors are looking for and what the readers expect.

After you’ve done your reading and you’ve got an idea on the expected outcome, take a moment to consider how your content might be re-used. If you plan to write about the same topic for several audiences, keep this in mind during the writing process. For example, while researching for a talk I’m giving at LinuxCon Europe, Speaking Their Language: How to Write for Technical and Non-Technical Audiences, I realized that writing an article first would make planning my talk easier. Had I planned my talk first, odds are I wouldn’t have gone back to write the longer piece (in this situation, an article) later. In either case, the research would be the same, but one approach (write the article, then the talk) is a more efficient use of time than the other (write the talk… never get around to writing the article). Deciding that I could write for Opensource.com readers in addition to LinuxCon conference attendees helped me decide which piece to write first.

Example: Writing for expert audience (developers)

Greg DeKoenigsberg, VP Community at Ansible (a popular open source automation tool), needed to let developers know about a new process, so he wrote an announcement for the developer mailing list. In his message, New process for acceptance of new modules in Extras, he didn’t need to define what Extras are because the ansible-devel mailing list audience should already be familiar with the term.

Greg’s mailing list post would also work well for a Ansible developer blog post.

Example: Writing for lay audience (community)

Robyn Bergeron, Community Architect at Ansible, wrote about the same process change, but for a wider community audience. In her blog post Ansible Extras Modules + You: How you can help, Robyn’s audience isn’t narrowed down to a mailing list of Ansible developers, so she defines her audience in the first sentence:

This brings us to a second lesson from Stephen King.

2. Invite the reader.

You can go back and revise your introduction later, but start with a sentence or two that grabs a reader’s attention and tells them what to expect.

An opening line should invite the reader to begin the story. It should say: Listen. Come in here. You want to know about this. ~ Stephen King

A strong introduction also helps you, the writer, stay focused on your audience and objective.

3. Tell a story.

Stephen King has lots of advice for storytelling, which is what tech writers are doing.

When you write a story, you’re telling yourself the story. When you rewrite, your main job is taking out all the things that are not the story. ~ Stephen King

Anything not essential to the story can be left out. Are you writing a HowTo for getting started with an open source graphics program? Consider linking to the installation instructions on the project’s site, unless they aren’t available in the documentation.

4. Leave out the boring parts.

When people ask me how long their articles should be, the answer is as long as necessary. Unless you’re writing in a confined space (for example, a one-page printed magazine), word count is pretty flexible. But if you’ve found that you’ve written more than 1,000 words for a technical article, or 500 words for a project update, re-read your text to see whether you’ve accidentally included boring parts. King says to leave those out.

Mostly when I think of pacing, I go back to Elmore Leonard, who explained it so perfectly by saying he just left out the boring parts. This suggests cutting to speed the pace, and that’s what most of us end up having to do (kill your darlings, kill your darlings, even when it breaks your ecgocentric little scribbler’s heart, kill your darlings.) ~ Stephen King

If you have much more than 1,000 words, and no boring parts, consider breaking your piece into smaller, more digestible chunks, such as a two-part series.

For example, Greg’s post to the ansible-devel mailing list omits details about developing modules. Instead, he provides a link to module guidelines. After all, he wasn’t writing for an audience of Ansible module developers, so he could leave out those boring parts.

In the example blog post to a wider Ansible community audience, Robyn provides a brief background:

Folks who keep an eye on the various Ansible repositories have probably noticed that your friendly neighborhood Ansible community team … have been digging through a pretty sizable backlog of issues and pull requests, primarily in the Extras and Core modules repos. … One of the main issues we’ve identified is, quite simply, bottlenecks in process…

After stating the problem, she explains the solution:

And thus: A new process has been born. I encourage you to read the details, particularly if you are interested in helping with reviews, or are already contributing to Ansible, which were outlined by Greg on Friday on the ansible-project and ansible-devel mailing lists. That said, here are the important highlights …

For the community audience, Robyn links to the boring parts, which include Greg’s post for the more technical audience, and Ansible documentation, module guidelines, and how to contribute.

Outlines

In addition to a strong introduction, an outline can help you stay focused on your audience and goal. Here are a couple of sample outlines:

News or community announcement:

• Introduction (invite the reader in)
• Provide a brief background (state the problem)
• Share the news (explain the solution)
• Conclude (include important dates or action items)

Technical article, tutorial, or whitepaper:

• Introduction (invite the reader in)
• Provide a brief background (state the problem)
• Share the news (explain the solution)
• Get technical (HowTo steps, FAQ)
• Conclude (include important dates or action items)

Depending on what you’re writing, you may want to include additional resources after the conclusion, such as documentation links, press contacts, or community resources, such as links to social media accounts, IRC channels, and mailing lists.

The Care and Feeding of the Press suggests including a fact sheet with a press release, but the list of facts to include also works well for project updates and announcements. A fact sheet should include:

• What the product is
• When it was first released
• What platforms it runs on
• What the configuration requirements are
• How much it costs
• Contact people for the press
• URLs and other contact information for the general public

What the product is, when it was first released, what platforms it runs on, configuration requirements, and cost are good to include in the beginning of an announcement or article.

After you’ve finished your draft, take a break and revisit it with fresh eyes. Before making revisions, getting input from a couple of colleagues is a good idea. If you don’t work with anyone who has lots of writing experience and knows your subject, reach out to your network. Ideally, you want feedback from someone who will be brutally honest and thorough, not someone who will stroke your ego. In any case, remember that you don’t have to accept all suggested revisions if you don’t agree with them—your name is attached to your writing, so plan to take responsibility for what ends up in the final draft.

5. To edit is divine.

To write is human, to edit is divine. ~ Stephen King

Don’t take criticism personally; instead, approach it with an open mind. For example, recently a colleague told me to cut almost a third of an article out of my draft because I had the beginnings of two incomplete articles, instead of one complete story. He was right, and my article was better because I accepted his suggestion.

Now you’ve decided what to write about and who you’re writing for. You’ve done your research. You’ve sketched an outline. And you know how best to edit whatever you write. What’s next?

6. Start writing.

The scariest moment is always just before you start. After that, things can only get better. ~ Stephen King

More writing tips

Doc
Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.