This article will try to give you some guidelines on writing articles. It is not meant to set down laws about how you must write; they are just recommendations. This article might be particularly useful for people who are new to writing for a magazine.

It is good to keep in mind the criteria that the editors follow when revising your article. Firstly, the article must be clear, well structured, and easy to read; it must be accurate; it must be at the right level for the target reader and it must use correct and appropriate English.

I will now look, one by one, at the basic steps in writing a good article.

Preparing an outline

The first stage is the preparation of the outline. You will need to have your outline approved before you start writing the actual article, and you may need to spend some time getting it right. The outline is the skeleton of the article, if it is poorly designed, then the article will be more difficult to read.

Each point must clearly show what it is describing or explaining, and why

It should be possible to have a clear idea of what the article is about through the outline, and it has to make sense to the person reading it!

Each point must clearly show what it is describing or explaining, and why.

There are several “models” of outlines that you can use. Here are a few:

Model 1

• Introduction to the problem
• Explanation of the basic concepts
• Application of these concepts
• Possible complications
• Explanation of possible complications
• Conclusion

Model 2

• Introduction to the problem
• Main points of the problem
• Explanation point 1
• Explanation point 2
• Explanation point 3
• ... more points here ...
• Summary/other
• Conclusion

Model 3

• Introduction
• How it works - in general
• A closer look
• Another closer look
• Behind the scenes
• Summary/other
• Conclusion

Choose the model that you think is most appropriate, or make up your own as long as it makes sense.

Sections and headings

The outline for your article should show clearly defined “sections”. Each section should have a meaningful heading. While you are writing the article keep the outline visible, and make sure that each section you write fulfils the purpose that it is given in the outline.

If you are explaining something technical, try to give straight forward examples or exercises that the reader can do while reading the article in front of his or her computer. For example, if you are writing about shell basics, and about simple ways of viewing the file system, give an appropriately simple exercise:

To see the list of files in the current directory, type ls -l

It sounds obvious, but often writers forget to do this.

Paragraphs

Within each section, split up what you have to say into paragraphs. Each paragraph should present one item, or one element of a larger item. Give the paragraph a simple outline itself.

Always try to find the clearest, simplest way of saying something, but not so much that you over-simplify the subject: keep in mind the level of your target reader and you will not go wrong.

Always try to find the clearest, simplest way of saying something, but not so much that you over-simplify the subject

Avoid repetition: this is a common error for many new writers. From the need to “fill in space”, the same thing in different words is written a couple of times over. This can be annoying, but more often is confusing for the reader. Avoid waffle. Write what you need to with as much detail as is required: but no more. Like repetition, waffle usually just confuses and frustrates the reader. If you cannot think of anything else to say, and further research does not come up with anything else that is relevant and interesting, stop writing.

Sentences

Try to use short sentences. Long sentences are fine for literary descriptions, but in a magazine they can be hard work for the reader to follow. Look at this sentence:

The first thing that comes to mind is to try to use the -h option, which often gives additional information about a command, but if we type cat -h nothing relevant is printed, except for a hint to use the --help option, so we try running cat --help and a simple description of some of the options is printed out: the meanings of which are quite obscure.

Now look at it after it has been adapted to a small number of shorter sentences:

The first thing that comes to mind is to try to use the -h option, which often gives additional information about a command. If you type cat --h nothing relevant is printed, except for a hint to use the --help option. If we then try running cat --help, a simple description of some of the options is printed out: the meanings of which are quite obscure.

The second version of the sentence is much easier to follow: especially if your reader knows nothing about the common -h and --help options for commands. Do not use brackets or dashes excessively. Use brackets when giving an example, or additional information. Swap excessive brackets or dashes with commas, and vice-versa.

Try to use short sentences. Long sentences are fine for literary descriptions, but in a magazine they can be hard work for the reader to follow

When referring to other people or users in the article, use “he or she”, and “his or her”, rather than just “he” or “she”, “his” or “her”. Write in the second person: that is, talk to the reader directly, using “you will find”, rather than in the third person: “one will find”

Use the imperative mood: “type this”, as opposed to “you should type this”, when explaining how the reader should approach a problem, as well as when giving instructions. For example: “Get involved with the GNU/Linux community to get the most out of using GNU/Linux”, rather than, “You should get involved with the GNU/Linux community in order to get the most...”.

Words

Always check spelling with a spell checker or dictionary.

Be aware of the level of your language: use appropriate language for the level of the target reader; do not use “literary” language, say what you need to say in a straight forward manner.

Articles in Free Software Magazine tend to be semi-informal: the way you would talk to an intelligent relative when you were explaining something of popular science to them

Check the formality of your language too: you do not write in same way to a friend in an email as you do in a letter to the government, or when applying for a job. Articles in Free Software Magazine tend to be semi-informal: the way you would talk to an intelligent relative when you were explaining something of popular science to them; treat the reader as a friend or acquaintance, without being overly informal, personal or vulgar.

Always treat the reader as an intelligent person who wants to know about the subject you are explaining or describing.

Always check spelling with a spell checker or dictionary

Avoid trying to use big words to make the article sound more “intelligent”; remember that you are writing an article, rather than trying to impress anyone.

Conclusion

Writing is a skill that is not usually learnt overnight.

If you are serious about writing articles (technical or not), for Free Software Magazine or any other magazine or book, you can learn best by example. Read as many articles as you can, and try to understand what is good or bad about them. Then mimic the good points, and check that your articles do not fall down on the bad points!

Hopefully, these suggestions will be useful to new and even experienced writers. If you find them helpful, keep a copy of this article to hand when you are writing, and use it as a guide. You can also use it when you are reading over a finished article, to see if it follows the recommendations.

Good luck!