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!
