How to Write Clearly

Copyright (c) 2003 by Jennifer Vesperman. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at


Several times, I have had people tell me they'd like to write a book review or a course for LinuxChix, but they don't feel they can write 'well enough'. I'm writing this as a way to help you improve your writing. Please do not take this as a guideline for how good is 'well enough' for LinuxChix - it's not. It's intended as a way to help people who are uncertain of their ability to improve.

This is nota guide to writing professionally. If you want to write professionally, I recommend that you to go to your local library, talk to the librarians, and read almost every book they have on professional writing and getting published. This document is a basic guide for the average person who wants to improve the standard of their writing.

If you want to write something for LinuxChix and want someone to edit it or help you with the actual writing, contact the volunteers mailing list on volunteers at and ask for help.


The first thing to think about is the scope of your document. How large a topic should you cover? If you want to write something in an afternoon, that only takes a few pages, you will not be able to write a comprehensive guide to Linux! But you could write a review of a book you have already read, or write down an explanation of how to do a simple task. Your ability to judge scope will improve with practice.

Pick a topic, then pick a single aspect of that topic that is small enough to write in the time you've given yourself. Even with my book (Essential CVS), I determined what was within scope, and what wasn't. (If I hadn't, I'd still be writing it.)


Once you have your topic, and have narrowed down the scope to something you can manage in the time you have allowed yourself, break the topic up into smaller pieces. To use this document as an example, I broke up 'how to write well' into topics like 'scope', 'structure', and 'audience'. A book review might discuss who the book is for, what it covers, and whether it is a reference or a textbook. Lay out each section of the topic on the page, as headings if you want them. (If not, lay them out anyway and remove them for the final copy.) Add the special headings 'introduction' and 'conclusion'.

For each section, write a paragraph or a few paragraphs about the topic. Then write a phrase or a sentence or two to link that topic to the next, or to link that topic from the previous one. (In this section, the link is the phrase 'Once you have your topic'.)

If your section is large enough, you can break it down further into subsections. Break each section down until you have small enough pieces to be comfortable writing them. Try to write one thought to each sentence. One aspect of a subtopic to each paragraph. One subtopic to each section. One topic to each article or chapter.

Your introduction should explain to your readers what you're planning to tell them and why. Your conclusion should reiterate that. Some people can't understand things until they know why they're being told it. Some can't understand why they're being told until after they've been told. I'm the first type of person - and my weakness as a writer is with conclusions.


Keep in mind who you're writing for. A writer's job is different from most real-time communication. In speech, online chat, mailing lists, and other real-time and nearly real-time communication, if your audience doesn't understand they can ask you. If your audience doesn't understand an article or a book, you usually can't fix it until the next version - and sometimes can't fix it at all. Always keep in mind the sort of person you're writing to, and try to use terms and phrases that they will understand.

Knowing your audience can also help you limit the scope of your document. If you decide that you will write an article on using iptables that is aimed at experienced system administrators, you will write a very different document to an iptables article aimed at computer laymen who want to produce a simple firewall for their home networks.

Accuracy and Research

If all you know about a topic is 'hey, I managed to get it going on my system', you can still write an article on how you got it going. There will be people who find that interesting and valuable information. If you want to write more, you will need to research the topic.

It is perfectly valid to read the man page, test your understanding, and rewrite the same information that is on the man page (audience: system administrators) in a more generally readable form (perhaps for novice users). But do test your understanding, that is part of the research. Try to be as accurate as you can.


If you are writing for a specific publication, that publication will have a preferred style. Academic journals have a rigid style, most magazines like things more informally written. LinuxChix is very informal - if most people can understand you, it's good enough.

We do have readers from all over the world. For their sake, it is important that you try to use the words you mean - if you use a phrase like 'the wire had been stripped bear' instead of 'the wire had been stripped bare', a reader who is looking up words in a dictionary is going to wonder what an omnivorous mammal has to do with computing.

Good spelling, grammar and punctuation can make your writing more readable, but don't worry about them so much you can't get the article written. If you don't trust your ability to spell, write clearly and punctuate, ask someone whose writing you trust to check it for you.


LinuxChix is always in need of reviews, and the Linux Documentation Project always needs articles and documents written. Many open source and free software projects need writers. Most people are capable of writing well enough to be helpful, but need a few techniques to help them. Hopefully, this article has helped you learn enough to get started.

And if you want to write something for LinuxChix and want someone to edit it or help you with the actual writing, contact the volunteers mailing list on volunteers at and ask for help.