Writing Technical Articles - Part 3
To recap, you've created a plan and an outline for your article. You've also added code samples or created the "to-die-for" tool or utility. And you've written your article as clearly and concisely as appropriate. Now it time for the scary part: letting others see your work. Getting others to review and comment on your work is an important step before exposing the material to the rest of the world. There's nothing worse than putting lots of the time and effort into creating a great article only to lessen its value with technical errors, simple omissions, and grammatical errors. Catching problems now will save you from embarrassment later.
If you are writing book or other technical publication, it is common practice for the publisher to assign a technical editor to work with you as you complete each section. I've been a technical editor for a couple of technical books where it was my job to test code samples and processes, spot misinformation and omissions, and otherwise make sure that the book is technically accurate and sound. In a sense, the
technical editor is the reader's advocate. The reader, for the most part, assumes that the information in the article is accurate and technically correct. It's up to the editor to make sure that it is. This requires that the technical editor read each section, test each sample, and follow each procedure step-by-step to ensure accuracy.
In addition to a technical editor, there is also an editorial or copy editor whose job it is to correct misspellings, edit grammatical errors, and generally, make sure the article is ready for publication. Although the process may vary by publisher, usually before the article gets to this editor, the article goes through a condensed technical review by one or more third-parties with knowledge of the subject. It is the job of these reviewers to perform a sanity check on the article to ensure that it meets the goals established by the author. They answer the basic question as to whether the article adequately enlightens the reader on the subject.
As painful as it might sometimes be to have someone critique your work, a good writer welcomes comments and suggestions from others. Finding mistakes is not an indictment that the author is negligent, sloppy, or misinformed. Writing a great article can be hard work and requires that the author pay attention to numerous details as writing progresses. Even the most experienced authors overlook details and make mistakes. It's also easy for an author to make assumptions about the knowledge level of the reader. Something that might seem crystal-clear to a writer may be unclear and puzzling to the reader. Technical reviewers can step back and look at the subject material from other angles.
It's a good idea to line up technical reviewers as early as possible in the planning stage. It's also a good idea to have more than two or three reviewers in case a reviewer is unable to complete the review for whatever reason. When submitting the article for technical review, it's a good idea to set the expectations of the reviewers. The goal of these reviewers is to check the article for technical details. You should clearly state this and that the copy editor will correct grammar, spelling errors, and so forth. As you read through the reviewer comments, you shouldn't hesitate to ask the reviewer for clarification on issues that are unclear. And if the rewites and additions are extensive, it's also a good idea to let the copy editor take one final editing pass through the article.
Once the article has gone through these steps, it is ready for publication. While the steps outlined in this series of articles may seem daunting at first, they are designed to help the writer and the reader get the most benefit from the article. After you have been through the process once or twice, it will seem logical and become second nature to you. Hopefully, this blog has removed some of the mystery from writing and publishing technical articles. Sharing your knowledge can be a rewarding experience for you and the customer.