Compartilhar via

Writing Technical Articles Part 2

  • Artigo

Continuing my previous blog on writing technical articles, now that you have a plan, it's time to create an outline. If done correctly, the outline can serve as the table of contents (if you use a TOC) for your article. Magazines and technical publication articles typically do not use a TOC; instead they usually use an overview (or hook) of what the article is about to get the reader interested in reading further. An outline also gives you a chance to see the flow of the sections of your article. Does one section flow naturally into the next section? Does the design of the different sections make sense? For example, the following is an example of an outline for a section (or for an entire article):

Overview
Benefits
Brief examples
Notes and cautions
Steps to setup and use
Expected results of following the steps
Troubleshooting steps for any potential issues
Conclusion
Additional Resources

Now that you have a skeleton for the article, it's a good time to start adding meat to the bones. A good way to get started is to put yourself in the reader's shoes and ask yourself what would you need to know to use or understand the feature. Use this as brain-storming session; write down all questions that come to mind. You can always sort or eliminate some of them later. For example, using our outline, you could ask:

  • Overview of the feature (or tool or utility). What is it? What problems does it solve? Where does it fit into other technologies? What is the basis for the feature; does it incorporate other technologies?
  • Benefits of the feature. Why would readers want to use the feature? How can it make their jobs easier? How is using this feature better than using some other technology?
  • Provide some brief examples of using the feature. Describe common, realistic scenarios a user might face and how the feature helped solve the problem. It is helpful here to use the third-person narrative style: "Mary works at the Acme company counting widgets. Using this new feature saves her lots of time and helps make her job much less tedious."
  • Add any notes or cautions. Will it require that the user modify the Windows registry and risk corruption? Is it compatible with all OS's? Should it, and any associated components, be installed in a specific order? Is it incompatible with other utilities or tools? This also a good place to specify any prerequisites needed to run the procedures in the next section.
  • Describe the steps to install, setup, and use the feature. To help you use the right tone and level of detail, you should look at the help topics included with other closely related features or applications. This will also give you examples of how to apply formatting and numbering. For example, items that the reader has to look for in the user interface should be bold; look for examples of how to use indentation and whitespace in code samples to make it easy for the reader to read and see where one construct ends and another begins. Styles will vary from one publisher to another so it's a good idea to check with the publication's editor before writing the topic. If you are one of those daring souls who writes the article before actually having a publisher, you can look at other articles in the same publication for examples. It is also helpful to include pictures that show the reader what they should see as they work through the steps; for example, pictures of any dialog boxes that the reader will use to set options, block diagrams of the process, before and after screen shots, and so forth.

Note: Instead of buying graphics editing software, I primarily use Microsoft Paint to create and edit all but the most detailed pictures in my articles. Paint is very easy to use and better yet, it's included for free in Windows. All you need to do is press the ALT and Print Screen keys and then paste into Paint. Of course, there are endless freeware amd shareware applications on the Internet for more detailed graphics work.

  • Describe the expected results. Explain exactly what they reader should see so they know if they followed the steps correctly. Here again, it is beneficial to include screen shots.

Once you have refined the outline and exhausted all of your questions, it's time to start writing. This should just be a matter of answering the questions you wrote down as clearly and concisely as necessary, with emphasis on conciseness. Readers, especially developers, are primarily interested in getting to the "good stuff" as quickly as possible. And though the temptation may be great to try and impress your audience with your elegant prose, it's best to stick to your plan and the questions you jotted down.

In most cases, you'll want to delay writing the overview and conclusion sections until the other sections are written. For the overview, this gives you a chance to look over the sections that you ended up including in the article (through rewrites and editorial changes) to provide a high-level view of the subject, preferably in such a way as to make the reader want to read further. For the conclusion, this allows you to briefly reinterate the benefits you already described as well as offer advice for the next steps readers can take to increase their knowledge of the subject.

As you write, keep in mind the three C's: Clarity, Conciseness, and Convenience. Make the subject as clear as possible. Keep it as concise as possible by using just enough words to adequately explain the topic, but no more. And finally, make learning as convenienent for the reader as you can by adding formatting and whitespace to highlight key points, using targeted samples and illustrations to add to your descriptions, and providing links to additional resources.

I'll end part 2 here and post part 3 shortly where I'll describe the review and editing process.

Comments