The structure of a how-to article

If you're new to technical writing, but would like to write an article for Technically We Write, you may be stumped by "How to write a good how-to article?" Let's help you get started on your first article.

Introduction

A how-to article should start with a brief introduction to "set the stage" and establish context. You don't have to go overboard with this introduction; the reader has already clicked into the article, you don't need to "sell" them on why they need to read it.

If you're writing a how-to article about a task you do all the time in technical writing, such as how to start a new project in Oxygen, how to create a new page in Drupal, how to format a table in Word, or how to define styles in LibreOffice, your introduction might say that you use this tool every day, and this is a common task you do with it.

You might also set the stage with an example that the reader can follow, such as "When I wrote my last ebook using LibreOffice Writer, I relied on styles. Here is how I defined a style to use for chapter titles." The reader now understands the background for this task, and can follow along with the rest of the how-to article with that understanding.

Break up the text with section headings

Help the reader to follow along by breaking up large blocks of text into smaller sections. Think of these sections like separate steps of an algorithm, with each step in its own section.

Dividing information into smaller chunks helps the reader to understand a complex activity. With this organization, a new section heading tells the reader "we're done with the previous step, now let's do the next step."

Think carefully about how to describe the steps in a how-to article. Each step should be self-contained. Avoid footnotes and asides in a how-to article; if you find the need to add a footnote, reconsider how to incorporate that text into the text body.

Show, don't tell

Where possible, consider replacing long blocks of text with a diagram or chart. Removing text may seem counterintuitive - our job as technical writers is to create content. But the old saying is still true: a picture is worth a thousand words. Consider how to provide visual examples for your reader. Show the steps rather than describe it. 

The average how-to article on Technically We Write is about 800 words. Some longer articles are over 1,000 - although those usually include HTML, XML, or some other form of "code" that bulk up the word count. But other successful articles are as few as 400 words. These shorter articles replace paragraphs of text with an image. It's easier to describe a step in a process by including a screenshot.

A brief conclusion

It's awkward for readers when an article just stops. Provide a brief wrap-up at the end of your article to signal that the how-to process is complete. You can write this conclusion in several ways; my preferred method is to summarize the "destination" of the how-to article, and encourage the reader to make it their own.

Writing a how-to article doesn't need to be a daunting writing assignment. Provide a brief context for your reader, then describe the steps to complete a task, with each major step in its own section with a section heading. Use images to replace long paragraphs. Write a brief conclusion to signal the end of the article.

And that's how you can write a great how-to article! Use this formula as a guide to write your first article. At Technically We Write, we encourage you to share your knowledge with our readers, and write a how-to article about your favorite tool or technology. Everyone is welcome to contribute to Technically We Write. We'd love to share your story!