How to write an article

From Web Education Community Group
Revision as of 16:14, 22 May 2012 by Cmills (Talk | contribs)

Jump to: navigation, search

There isn't really any single right way to write a tech article, but as with all things, there are mistakes to be made, and things to stay away from. In this article I'm going to give you a loose process to follow when writing an article, as well as some rules/points to keep in mind that may make life easier.

Process for writing an article

So, let's go! When writing an article, I would suggest you follow the below steps. When you become more confident at writing articles, you can probably drop or few or build your own process. It's all about having a workflow that works for you.

Make it clear what you're writing about

When you are writing about a topic, make sure that it is clear in your head what you are writing about, and that you can easily communicate that to others. When you want to write an article or series of articles, start by writing:

  • A placeholder title, for example "CSS animation basics". Don't obsess about this right now — you can always change it later.
  • A list of required knowledge for your article, eg "Intermediate to advanced HTML, basic CSS."
  • A single sentence that describes clearly what the purpose of your writing is. For example "An introductory tutorial that teaches the basics of CSS animations."
  • An extended outline/abstract that says what your article does, like so:

"This article gives a bit of background on CSS animations then dives into a step-by-step tutorial to show how to build a working animation. Along the way we'll explain what all the related properties and their different values do, what browser support is like, how to provide fallbacks for older browsers."

It is important to get this information straight in your head before you write an article. If you are not clear on the scope and can't explain it to others, then you will probably find it harder to write about. This is not to say that the scope cannot change as you write the article. But try to keep "scope creep down" as much as possible. Other things can be covered in later articles.

Write a clear structure, and loosely stick to it

Write out all the top level headings that you will include in the article, to give you a good idea of what the structure will be before you start. For example, in my recent Making a move with CSS animations article, I first wrote out the structure like this:

  • Making a move with CSS animations
    • Introduction
    • How mature is the technology?
    • Basic syntax
      • Defining an animation
      • Applying an animation
      • How many times do we want it to happen?
      • Varying animation rate
      • Animation delays
      • Start to end, or back and forth?
      • animation-fill-mode
    • Animation shorthand
    • A More involved example
    • Summary

Then I filled in all the gaps between the headings. Again, the structure can (and probably will) change somewhat as you are writing it, but you will find things easier if you have an idea of the structure before you start writing, and you can see how much you've got left to write.

If the material ends up taking up more than one article, that is fine. Just write more than one outline, and deal with them separately.

Make sure the theory works in practice

This is not something I always do, but I would advise it wherever possible. Before you start writing about some code that you think should be possible to implement, try it out first to make sure it'll actually work; a stripped down skeleton version at least. I've had a problem a couple of times where I have ended up having to rewrite an article quite significantly because a fundamental part of my code doesn't actually work in practice for whatever reason.

Write clearly and purposefully

In terms of actual writing conventions, we have started to put together a Web Education community group style guide for your to follow. You should feel free to add to this as well if you have any good points to make.

Your personal writing style is a different matter. I personally don't want to chain everyone to a strict corporate writing style, because

  1. I think that is boring
  2. It is a community site, so shouldn't have a single regimented author voice

So your writing styles can vary quite widely. What I would like to stress though, is that you should make your writing as clear and purposeful as possible. Remember that you are writing educational material to help people learn, not the old testament or Lord of the rings. A bit of flowery poetic language is good for making things more interesting in place of Lorem Ipsum inside a code example, but it is no good if it gets in the way of understanding the explanation of that example.

And I believe a bit of humour is always good in technical tutorials/references, to break up the monotony and make things a bit more fun. But if it is too often and too extreme, it can become tiresome and put some people off.

Remember that tenet about making your web content accessible to as wide a variety of users as possible? This refers to human language content too!

Get your first draft reviewed

Once you've written a relatively stable first draft, get it looked over by 2 or 3 peers whom you trust. Get them to give you feedback on how the article is progressing, what is good, what could be added to make things better, and what needs improving. See [How to review an article] for more details on how to provide feedback.

Rewrite and encourage contributions from others

Get a final proof

Tell the world

Rules of article writing

The Queen's English?

Don't obsess over perfection

Set reasonable deadlines

Use reasonable assets for your medium