Imagine that you were in dire need to learn a particular aspect of some particular technology. In your research for an answer to your question you arrived at two articles written by two different authors with polar writing and technological abilities. If you only had time to read one of the two articles, what do you think you, personally, would benefit from more:
- An article writen by an author with extreme expertise in the particular technological field, but with horrendous writing skills, or
- An article written by an author with strong writing skills, but only an average grasp of the technical material?
If you answered (1), then I would wager you've been lucky enough not to stumble upon such an author in the past. As editor for 4GuysFromRolla.com, I have had hundreds of articles submitted by hundreds of authors from around the world. In reviewing these, I have seen both ends of the spectrum, and everything inbetween. Clearly the worst article is one written by an author with a poor understanding of the technology and lackluster writing skills, but a close second worse is one written by someone with a keen understanding of the technology, but without the writing skills to transfer his immense knowledge from his brain to the written word.
If you think about it for a moment, it makes complete sense why the writing prowress of an author is of paramount importance: even if you know it all, others cannot benefit from your knowledge if you cannot adequately express your intellect.
Improving Your Writing Skills
While everyone will agree that one can improve their technological skills in a particular field, I've found that many don't seem to think that they can improve their writing skills. While really, really good writing is an art form, and can likely not be learned, but rather must be innate, good writing is a skill that can be learned as easily as good programming skills. (Note: those who are really, really good writers, don't use expressions like, "really, really.")
So how do you learn to become a good writer? Well, how did you learn to become a good anything? Through:
- Practice,
- Mimicking those who you know/think to be skilled at the thing you're trying to learn,
- More practice,
- Learning from the advice/suggestions of those who have come before you, and
- Even more practice!
Learning how to be a good writer is no different. Here are some random suggestions from yours truly, little bits of advice I've picked up over the years either from others or things I've learned on my own:
- Before you write the first word, write down in a sentence or paragraph, or half-page synopsis what you are wanting the reader to learn and what your content aims to show. (The duration of this depends upon the breadth of the content. For example, a short online article needs just a sentence or two. A book could take half a page or more.)
Imagine that you wanted to write a short introductory article on XML. Your synopsis might look like:
"This article will introduce the reader to XML, covering the benefits of XML, what problems it overcomes, and the XML formatting rules. The article will also examine some simple common use cases for XML, such as sharing data between disparate platforms."
- After you write the synopsis, but before you write the first word, create an outline. Start by filling in the top-level items (the I, II, III items) before filling in any particular top-level items' sub-items. After you have created the top-level items, return to the synopsis and ask yourself, "Will the reader learn what I want them to learn given this high-level outline? Am I covering the material I set out to cover?" Make any needed changes to the top-level items at this time. An example outline for our XML article might look like:
I. XML - What is It?
II. Motivation for XML
III. Benefits of XML
IV. Common XML Use Cases
V. XML Formatting Rules
Also consider reordering top-level items. Try to place yourself in the reader's shoes, and ask yourself if the ordering makes sense. Would it make more sense to move the IV item after V? Or perhaps IV should be moved directly after I. Its optimal position depends on your audience, their experience level, and what they are trying to get from your article.
- Once you have shored up the top-level items, start adding sub-items to the various top-level items. I usually don't aim for a too granular amount of detail here; rather, I usually go only one or two levels deep (like A, B, C sub-items and then i, ii, iii sub-sub-items).
- At this point, you are ready to begin writing. The first thing you will write, even if you forgot to include it in your outline, is an introduction. The article's introduction will essentially be restating the synopsis we wrote down to begin with, but in more detail. Next, for each high-level outline topic, you should start the discussion with an overview of what will be covered in that high-level topic.
Think of a technical article as a journey for the reader, one that ends with a new piece of knowledge.1 The introduction for each section is akin to directions: it summarizes the journey in a short, concise manner, giving the reader an quick overview of where their trip will take them, and what they can expect to encounter.
When you complete a paragraph, reread over the paragraph and ask yourself if it makes sense. Again, put yourself if the reader's shoes and ask yourself, "If I was new to this technology, or if I was learning about this concept, would this paragraph make sense? Would I understand it?" Perhaps there are terms or buzzwords used that have not been previously defined. Perhaps you had subconsciously "skipped over" important parts to understanding the concept you're trying to illustrate because you find these parts to be trivial. However, a reader learning the technology might not have a complete understanding or picture without these missing parts.
At the end of high-level sections from the outline, be sure to summarize the material covered. Take a step back from the techno-jargon and reiterate in very simple English what the reader has just learned, and its application. Let the reader know where you'll take them next and how what they've just learned will play in. Explain in conversational English so a Luddite could understand.
This is just a smattering of little bits of advice that I use daily in my writing. If you are interested in strengthening your writing skills, I would encourage you to try adopting some (or all!) of these suggestions, and then, and most importantly, practice. Write articles for technological Web sites, or, if nothing else, create your own Web site and post them there. Share them on usenet, or online forums, and see what your readers say/ask. Do they have questions about certain things? Were some things unclear? Take this advice to heart and learn from it.
1 - Apologies for the cheesiness!