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.
But, why write?
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
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.
Audience
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.
Planning
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.
Developing
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.
Organizing your material
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.
Rough draft
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:
-
Start at the beginning - Writing the introduction is a natural place to start and planning the route will ease the journey. I often start with the introduction, but with the explicit assumption that I'll throw most of it away in the first revision. This seems to help me get going.
-
Start at the end - Writing the conclusion first makes a clear statement about the destination.
-
Start in the middle - Start with the part of the document that you feel most confident about.
-
Throw one draft away - Just assuming that the first draft is to be thrown away can help grease the writing wheels. When the draft is done you may decide it's good enough not to bother starting from a blank page again.
-
Develop alternative drafts - Writing multiple drafts from alternative perspectives can help you to find the best way to approach a topic.
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.
Editing the rough draft
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.
Revising the first draft
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.
Revising the second draft
The second revision of the draft focuses on the text of the article; the paragraphs, sentences, and words.
-
Revise paragraphs - Each paragraph should express one point. They should vary in length, typically between 30 and 150 words, not all long, and not all short. Use short paragraphs for emphasis, and long paragraphs for descriptive or discursive text.
-
Revise flow - Ensure that the narrative of the article flows smoothly from paragraph to paragraph.
-
Revise sentences and words - Use a variety of sentence constructions. Vary sentence length; short sentences for impact, long sentences for descriptions. Rely on your inner ear to find sentences that don't scan well. Rework any that sound awkward, imprecise or wordy. Spike Milligan said, "Clichés are the handrail of the mind". Substitute them for fresh, interesting descriptions. Prefer the active voice to the passive voice.
-
Revise for tone - Everyone writes in their own voice, but articles written for Overload should be a mixture of instructive, confident, explorative, and friendly; you should avoid preachy, arrogant, fancy, or overly academic and formal tones.
-
Revise the introduction - Check that it introduces the topic of the article. The introduction can also be used to grab the reader's attention, possibly by asking a question, or making a blunt statement.
-
Check the conclusion - The conclusion can be used to pull together all the parts of the article, it can rephrase the main argument, or it can reaffirm the importance of the topic. Above all it should convey a sense of completion.
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.
Revising the third draft
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.
Submission to Overload
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.
You'd write, only…
-
You don't have time - You should regard writing as an investment in yourself. You take time to educate yourself to keep your technical skills fresh and relevant. Writing is another important skill you should nurture. Try asking for some work time to write an article. Enlightened management will recognize your increased value to the organization. In order words, writing an article for Overload will get you a promotion!
-
You're not so good at writing - The hardest part is getting started, but by developing a regular writing habit you will improve with practice. We'll help you get through the writing process by discussing topics, approaches and editing drafts.
-
People won't want to read what you write - To publish seems to be calling for attention, inviting others to judge you. But the Overload audience is friendly and supportive and I've only ever received positive comments for my writing in Overload.
-
"Bjarne is smarter than me" - Probably, but we publish articles at all levels. An issue full of language extension proposals would not be fun for any of us.
-
You just don't feel good about this - Writing is much like public speaking, it takes time to gain confidence. Start with a small audience and build from there. Challenge yourself.
-
You mean to, but you can't get started - Take each stage at a time. It's hard to sit down at your desk with the goal of writing a book. A more manageable goal to set is to write a page, or even a single paragraph. As each milestone is achieved you build success upon success until you reach the greater goal.
-
You don't have anything to say - Trust me, you do.
You have no choice
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.
References
[Strunk] Strunk and White, The Elements of Style, Allyn and Bacon.
[Gucker] Gucker, Essential English Grammar, Dover.
[Dupre] Lyn Dupré, Bugs in Writing, Addison-Wesley.
