5.3. Writing the Text

At this point, your HOWTO has been organized, and bits of raw information have been collected, documented, and inserted into the outline. Good news: You're past the midpoint; it's all downhill from here.

Your next challenge is to massage all of the raw data you've collected into a readable, entertaining, and understandable whole.

It has taken quite a bit of work to get to the point where you can actually start writing, hasn't it? Well, the hard work begins to pay off for you now. At this stage, you can begin to really use your imagination and creativity to communicate this heap of dry, boring information in your own unique way.

It is beyond the scope of this document to provide a comprehensive guide to effective writing, so I won't try to go beyond the basics. In the "References" section, you will find a list of resources that cover the subject better than this guide could hope to. Consult them, and follow their advice.

For starters, here is some good advice from Politics and the English Language:

	A scrupulous writer, in every sentence that he writes, will ask himself at least four questions, thus: What am I trying to say? What words will express it? What image or idiom will make it clearer? Is this image fresh enough to have an effect? And he will probably ask himself two more: Could I put it more shortly? Have I said anything that is avoidably ugly? ...One can often be in doubt about the effect of a word or phrase, and one needs rules that one can rely on when instinct fails. I think the following rules will cover most cases: Never use a metaphor, simile, or other figure of speech which you are used to seeing in print. Never use a long word where a short one will do. If it is possible to cut a word out, always cut it out. Never use the passive where you can use the active. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. Break any of these rules sooner than say anything outright barbarous.
--George Orwell

And, from a purely stylistic point of view, I believe that the first-person perspective of many HOWTOs adds to their charm, an attribute most documentation in other forms sorely lacks. Don't be afraid to speak for yourself, use the word "I", or describe personal experiences and opinions.

If it hasn't become painfully obvious yet, the underlying principle of all these suggestions is simplicity. Your readers are already struggling with new concepts, so don't make them struggle to understand your language. Remember the KISS principle: Keep It Simple, Stupid!