Title: Editorial - On Writing

I am sometimes asked how one goes about writing an article for Overload. I usually rattle off an email with a few random thoughts about getting the text down and editing it into shape. This editorial is my attempt to properly address the topic.

In The Elements of Style [Strunk], Strunk and White describe the rewards of writing as:

"[The writer] will find it increasingly easy to break through the barriers that separate him from other minds, other hearts - which is, of course, the purpose of writing, as well as its principle reward."

Well quite, but people write either because they enjoy it, or because they know that it's good for them. I'm definitely in the latter group. Words do not flow from my fingertips in the same way that code does, but I know that I have benefited from improving the quality of my writing. Strunk and White continue:

"…the act of composition, or creation, disciplines the mind; writing is one way to go about thinking, and the practice and habit of writing not only drain the mind but supply it, too."

The distinguishing quality of a senior engineer is their ability to communicate ideas clearly and efficiently. I've seen talented engineers limit their progression, unable to project themselves beyond their immediate workgroup, because they do not take up opportunities to write or conduct presentations.

Selecting a topic can be the hardest part of writing an article. We all have a vast array of thoughts spinning around inside our heads, but it can be hard to pin down one that we think is interesting enough to present to others.

Don't judge your ideas too harshly. Something you think of as simplistic and well known will turn out to be multi-faceted and interesting under further examination.

Don't try to cover too much. It can be overwhelming to write about the architecture of an entire system, or even a hundred lines of code. Some of the best Overload articles are those that carefully examine a pattern, an idiom, or even a single phrase or keyword.

People naturally want to write about their successes, but we actually learn more from our failures. Learning to examine and share our failures is an important developmental milestone for us all, both as individuals and as professionals.

'Write about what you know', is the most common advice given to prospective authors. Indeed, draw from your own work experiences. Base your writing on problems you are trying to solve, and the solutions that could be deployed.

Conversely, I find that 'write about what you don't know' to also be true. A difficulty with writing about what you know, is that the topic material can be so ingrained in your being that it is no longer at the forefront of your mind. The process of researching and documenting a new topic can be easier than the introspection required to dredge up the reasoning for the everyday assumptions under which you operate.

Overall I'd say that the journey is more interesting than the destination. For me, the process of solving a problem is more interesting than a statement of the solution. For example, when I interview engineers I look for people who know how to go about solving a problem, rather than people who know the solutions to problems.

In all writing it is important to consider your audience. This is simple for Overload; your readers are people just like you. I have in mind professional software engineers who are self-educating but busy people. They are seeking a forum of peers in which to share their thoughts, learn from others, and discuss ideas.

Inexperienced writers often skip this important stage. Would we start coding before designing? Perhaps that's not the best analogy, but a simple plan can keep an article on track. Without a plan, the tendency is to produce a wayward collection of random paragraphs. The editing process then retrospectively imposes a plan, which rarely works out well.

This is the process of collecting the material that will make up your article. I personally have most trouble with this stage. I'm unable to capture all my thoughts on a topic in a single session. I read background material and build up a sheaf of hand-written notes before I reach for the keyboard. Jotting down potential sub-topics, key phrases, and supportive material like examples, references, and quotations helps me a lot.

Avoid starting by writing code. The text is more important than the code. The article should be about the writing the code, not what the completed code looks like.

Given a plan and a collection of notes you can now develop an outline of the article. The outline pulls together related material, showing how ideas are grouped and related to each other. This process helps bring balance to the article by ensuring sufficient coverage for each point.

At this stage it is important for you to adopt a state of mind where getting any text down is more important than getting the perfect text down. Forget grammar, punctuation, and spelling, just get started. Possible ways to approach a draft are to:

The difficulty with getting started is psychological; you must be in the right frame of mind to write. Any number of factors can contribute: time pressure, the location, or distractions. Write where and when you feel comfortable. Schedule time specifically for writing. Turn down the ringer on the phone. Close your office door (if you are so blessed). Go home. Go to work. Go to the library. Shut down your email client. Above all just focus on the present and set yourself achievable goals.

My favourite technique is to send myself an email. I feel totally uninhibited writing email messages. I can crank out a paragraph in about thirty seconds, a paragraph that might take me an hour with a word processor.

Having completed the rough draft it's best to take a break from writing, so that you can return to the text with a fresh mind. I find a good night's sleep works for me, others may prefer a couple of days, or even a week. The rough draft should be edited for substance rather than language. Don't waste time fixing up the text for publication, concentrate on which points should remain, and which should be eliminated.

Now is a good time to think about the length of the article. Overload magazine has no minimum or maximum article length restrictions, but we usually serialize articles longer than five pages. We rarely receive short submissions, which is unfortunate as they are very useful when composing an issue.

Check the draft against the plan. Has the objective has been achieved? Is the message clear, and has the main point been adequately addressed?

Test the draft against the outline, revise the organization to group ideas together and put them in the proper order. Balance the main points of the article so that they get equal attention, making sure that there is enough supporting material for each, not too much, and not too little. A hard, but important, step is removing content that does not contribute to the main point. For example, Allan Kelly makes excellent use of sidebars to further develop material that is surplus, yet still supportive to the main point.

The second revision of the draft focuses on the text of the article; the paragraphs, sentences, and words.

There are three excellent books that I often refer to during this stage of the writing process. The Elements of Style [Strunk] is a short classic that I mean to reread more often than I do. Essential English Grammar [Gucker] is a short guide that makes up for my not having paid any attention to my English teacher. And, Bugs in Writing [Dupre] is an instructional and beautifully presented book written specifically for engineers who write.

The final revision is for overall style, grammar, punctuation, and spelling. Read the text slowly, carefully, and aloud. Let your ear guide you. If some text doesn't sound quite right, rework it. You can also ask someone else to read and comment on your draft. Select a reader who will provide you with constructive and affirmative feedback.

Introduce titles and sub-headings to clearly identify topics. They can also pull the reader into the article as they browse through the magazine.

Use font effects sparingly; reserve them for emphasis to clarify meaning.

Articles should be submitted to the Overload editor after the second or third revision. An editorial board, comprised of the editor and a number of readers, manages the content of the magazine. The editor distributes the article to readers, who read the article for technical correctness and relevance. The readers return their comments to the author, who revises the article once again and resubmits the final draft to the editor. The editor performs the final proof reading before passing the article on to the production editor for inclusion in the next issue.

I hope this editorial has persuaded you that there are real benefits from writing for publication, and that writing an article for Overload or CVu is something that you can and should strive to do.