How to write an article

From Web Education Community Group
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. Humour can also be culturally-dependent, so that people from other cultures might not "get it" or might even be offended. So, have fun, but use caution.

Likewise, analogies to "real life" situations can be very helpful for conveying concepts, but can also vary by culture. Sporting analogies, whether to American football or to cricket, often don't travel well.

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.

You should send your article out for review when it is functionallty complete, but not perfect. You needn't get all details make absolutely perfect at this stage — getting feedback is what a first draft is for! But you should also make sure that you haven't got loads of unwritten code examples and section of prose at the point where you submit it.

Rewrite and encourage contributions from others

Once you've got feedback from others, start rewriting the article to fix the problems that have been brought up. And since this is a community effort, we should try to become as comfortable as possible with:

  1. Editing other people's work
  2. Having our material edited by others

Please, when you've submitted an article for first draft, encourage others to add to it and help improve it.

Get a copy edit/final proof

When you think the article is completely finished in terms of technical content, it is a good idea to get it proof read/copy edited. Don't get the proof reader/editor to delve deep into the code and the fundamental article structure at this stage: This should be a final check just to get rid of any last minute typos and other article silliness that might still be present.

At this stage, if the proof reader/editor does uncover a major issue with the article, it is probably better to delay publication and work out what to do to sort it out.

Tell the world

Once your article is published, send a link to it to the Web ED CG public mailing list to tell us all it has been published. Ask us nicely to help promote it via whatever appropriate means we have available. Ideas:

  • Twitter
  • Facebook
  • List of educators
  • Forrst
  • add your ideas here

Rules of article writing

These are not hard and fast "must do" rules, rather they are just suggestions that will make your life easier.

The Queen's English?

In terms of your writing style, you don't need to obsess about using completely correct "queen's english"; your writing being readable and clear is more important.

Don't obsess over perfection

At least, not at first draft stage. I've seen so many books and online resource delivered late because the author just couldn't stop obsessing over the details and fine tuning. As I said above, a first draft should be functionally complete, but not perfect. You and other contributors can work together in harmony to sort out all the problems as you go along. Learn to chill out and let go, and ask for help.

Set reasonable deadlines

You will inevitably be able to write an article more effectively if you set yourself a realistic deadline to meet. Don't try to do it in the next 12 hours because it won't happen. but don't make it too long either, otherwise you'll lose momentum and interest.

Only you truly know how busy you are, and how long it will likely take you to write an article. If you really have no idea how long it will take, just set aside an evening, sit down, and try writing a third of the article structure, to try to give yourself an idea. I usually find it helps to split the work into a few sessions, like say 2-3 evenings to write an article.

You need to discipline yourself a bit, otherwise it won't happen.

Save your work often

This is pretty obvious, but the number of times you'll lose work because of crashes or stupid mistakes is crazy. I tend to write my articles in a plain text editor, not a big WP package like Word or Pages, because text editors aren't as prone to crashes. If you are writing content for the web, you don't need a word processor anyway.

I also tend to create and save my work straight inside a git repo, and add/commit regularly so that you have a record of what you did, in case you mess up and need to revert to an earlier version.