≡ Menu

Repost: Tips on writing articles

As editor of TheServerSide.com in the past, I had a lot of opportunity to see what worked in online writing and what didn’t. Since it was a core part of my job to be efficient online, I also did a lot of research into various techniques, and while I certainly can’t claim to be an SEO expert of any kind, I can describe some things that can help online writing be more efficient.

This was originally written for TheServerSide.com, and was linked on the post submissions page; since then, they’ve mangled the formatting of old posts so it’s nearly unreadable, although the .Net version of the article is still formatted properly.

Tips on Writing

Writing articles for the web is a lot like writing anything else, with the main differences being that you have fewer limitations, and thus even more chances to lose your audience.

When you write online, it’s being written for posterity. Thus, write it as well as you can. You want to be very clear, and you want to make sure you’re not assuming things on the part of your audience.

Don’t say things in passing. Be specific. Your audience doesn’t have the time or interest to try to figure out what you meant. Trying to be fancy will only make you less effective as a writer. There’s no issue with having a personality or a style in your writing, but if the dominant feature in your writing is your style (and not the content itself) then you’re going to lose your audience.

Losing your audience is a bad thing.

The first sentence in your article is by far the most important. It needs to communicate why a given article should be read. If that one sentence is not effective, your article will start off with a smaller audience, because you will lose readers immediately.

The first sentence in each paragraph is also important. On the web, readers tend to scan more than read. If you put the topic sentence after the first sentence in the paragraph, chances are good that the readers will not reach it. They will have moved on to the next paragraph, or perhaps they will have stopped reading altogether.

It is all right if the subject of a paragraph cannot be completed in one sentence, but the topic sentence should be enough to communicate what the paragraph means. If the reader wants more explanation, the rest of the paragraph exists to provide it.

Short sentences are good. Long sentences are fun to write, and they are often quite natural for authors, but they are not efficient for web readers to scan.

Don’t use emphasis techniques like bold or italics any more than you absolutely need. If you feel that bold is necessary to make your point, then it’s likely that your sentence or paragraph is organized poorly. Highlights like bold or italics draw the eye long after the bold text is read, and the highlights actually lower comprehension.

Code samples are great, and usually required, but make them clear and complete. References to third party sources are all right, but the readers are best served by full code. Boilerplate code, like accessors and mutators, can be ignored with a comment, but it could be more effective if you used properties directly for simplicity … or, instead of including a long list of accessors and mutators, use Lombok. If you’re using Java, that is.

Remember that writing online is still writing. The writing process rarely lends itself to single drafts. It can happen, but it’s rare, and usually not effective.

For efficiency and good writing style, follow a set of simple tips:

  • Make an outline.
  • If the first sentence of a given paragraph isn’t enough to understand what the paragraph is about, rewrite the paragraph.
  • Make sure the article matches your premise! If the subject of the article is “Object Databases and Efficiency,” don’t spend half your text discussing the failures of relational databases. Talk about object databases and efficiency instead.
  • Make sure your spelling is correct.
  • If you use a word processor that provides grammar checking, you should allow it to suggest changes. Check your reading level, Flesch-Kincaid scores, and other data you can. The average reader wants to read at a sixth-grade level. If you consistently score much higher, your article will be hard to read. On the web, ‘hard to read’ usually means ‘unread.’ (This document, as originally published, received a Flesch-Kincaid grade level score of 7.8, for example. I haven’t checked the revised version, because I’m afraid to.)
  • Have people read your draft, and listen to every suggestion they offer. Don’t offer it only to experts; offer it to willing newbies, too. It’s all right to decide not to use suggestions, but your wider audience is going to think of many of the same things your test audience tells you. Constructive criticism is good, especially if it’s received before the article is published.
  • Avoid parentheticals like the plague (the plague is bad, no matter which plague it is.) If you have to use parentheticals, go ahead, but try hard to not overuse them. (They’re hard to read, and break the flow of text. Plus, they’re annoying.)

What I Do When I Write

I actually mind-map most of the things I write, with Freeplane, an open-source (and free) mind-mapping tool. I then draft a rough map for the article.

My central node is, naturally, the subject. (This article would have “tips on writing.”) Then I create child nodes for the central points that I think I need to make – the things without which I’d decide the article wasn’t worth reading.

This becomes my structure. If I have a child node that isn’t something I have to have, then it’s extraneous to the document, or my subject thesis isn’t correct.

These first vertices are the most important part of writing an article, to me; the rest I can usually figure out as I go, if I have to, because my important points (the second-level nodes of the map) should be clear enough and relevant enough to use as a guide for everything.

I usually fill out another few levels for each of the second level nodes, too, though, because they also should have supporting thoughts associated with them. (Otherwise they’re not supported; they’d better stand on their own, then.)

Then, I draft the article itself. The space each supporting statement should get should be roughly analogous to the size of the corresponding node in the graph; if a node in the graph is very short, yet the text for that node is very long, then perhaps my graph isn’t very complete… or perhaps the section is getting too much emphasis, which is by far the more common case. (Or, alternatively, I’m showing code, which drastically affects the size of a block of text. No way around this, sadly, other than hiding the code or providing a link to an external page, neither of which is effective.)

If it’s stated simply in the mind map, there’s no reason it shouldn’t be stated simply in the final product. (Corollary: state things simply in the mind map.)

Then I reread the article, a lot. I find willing victims as often as I can, and make them read it; usually I get unuseful and generic responses like “it’s good,” which boosts my ego some but, realistically, those responses don’t do much for me or for the article. I’m looking for constructive criticism, questions that come from the reader, things like that.

Remember: it’s a draft. As long as you keep that in mind, barbs thrown at you from readers won’t sting much. If they do, well, sorry – listen to your readers. Maybe you won’t factor in what they say (remember the list of tips earlier in this article?) but there’s usually a reason they think what they think.

Sometimes a point made by a reader emphasizes what you wanted to have happen – maybe you wanted the reader to wonder something, you know? If the comments are in line with what you desired to happen, well, that’s a win. If they’re not, well, that’s why you draft and that’s why you rewrite.

The concept is that a mapped article, if it’s able to be graphed properly, will naturally have a better, more cohesive structure for your readers, reducing signal-to-noise and guiding the author’s efforts. A draft process, detached from your ego, is designed to make sure that you aren’t using your writing as pure ego, which makes it more broadly appealing and useful.


I’ve spent a long time learning how to write well online, with varying results. I, too, am ego-driven, after all. However, I love to read well-written stuff, and as an editor for online and dead tree material, I’ve learned what works and what doesn’t. Hopefully you will find these tips and processes useful; I’d love to hear about alternative processes, too, because there’s more than one way to dig a hole.

{ 0 comments… add one }

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.