Write
Writing the Text
Hopefully by 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. If you're
working from an existing document make sure any new pieces of
information are in the best possible places.
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.
If it hasn't become painfully obvious yet all of these
suggestions are about keeping your documents simple.
Your readers are already struggling with new concepts, so don't
make them struggle to understand your language.
There are a number of classic guides to writing--many
of which are available on-line.
Their language will
seem old, but the messages are still valuable to authors today.
These are listed in the resources section. Also listed in the
resources section are a variety of sites that have
information specific to technical writing.
The Author Guide wouldn't be complete without
mentioning the Plain Language movement. Although
directed at simplifying government documents, Writing user-friendly
documents is quite useful. It includes before and after
writing samples. There's also a
PlainTrain
writing tutorial.
And any document that discusses writing for the web wouldn't be complete without
a nod toward useit.com.
The following articles may be of specific interest:
Writing for the
Web,
Information
pollution, and
Be Succinct!
(Writing for the Web).
There are many, many resources for writing web
documents--a quick web search for web
writing
will find lots of resources. (But
don't get too distracted--the ultimate goal is to
write, not to read about writing!)
Writing Style and Style Guides
There are a number of industry style guides which define how language
should be used in documents. A common example for American English is
the Chicago Manual
of Style. It defines things like: whether a period (.) should be inside or
outside of quotes
; and the format for a citing
another document. A style guide helps to keep documents
consistent--most corporations will follow a style guide to
format media releases and other promotional material.
Style guides mays also define how words should be spelled
(is it color or colour?).
The LDP does not require a specific style
guide; however, you should use a consistent style throughout your
document. Your document should be spell checked for a single
language (e.g. American English vs. British English).
The Reviewer's HOWTO currently lists a number of
conventions for LDP documents and is as close as it
gets to an official LDP Style Guide.
You can save yourself a lot of time in the editing phase if you
decide how you will write your document ahead of time. If you are
taking over someone else's document you may need to either: modify
your own style to fit the current document; or edit the
document so that it melds with the style you would like to
use from now on.
From a writing style perspective, use of the
first-person in a HOWTO adds to its charm--an attribute most
other documentation sorely lacks. Don't be afraid
to speak for yourself--use the word I
.
Describe your personal experiences and opinions.
Online Writing Resources
In the
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.
Edit and Proofread the Text
Once you've written the text of your HOWTO, it is time
to polish and refine it. Good editing can make the
difference between a good HOWTO and a great one.
One of the goals of editing is to remove [extraneous] material that
has crept its way into your document.
You should go through your HOWTO carefully, and ruthlessly
delete anything that doesn't contribute to the reader's understanding
of the subject matter. It is natural for writers to go off on tangents
while in the process of writing. Now is the time to correct that. It
often helps to leave a bit of time between when you write a document
and when you edit it.
Make sure that the contents of every section match the title of that
section precisely. It's possible that your original subject heading
is no longer relevant. If you've strayed from your original heading
it could mean one of the following: the original title was poorly
worded; the new material should actually go in a different section;
or the new material is not really necessary for your document. If you
need to change a title, check to see if the original subject heading
is still important. If it is make sure that topic is covered somewhere
else in the document.
When editing and proofing your work, check for obvious mistakes,
such as spelling errors and typos. You should also check for deeper, but
less obvious errors as well, such as holes
in the
information. If you are creating a set of instructions it may
help to test them on a fresh machine. Sometimes there
are packages that need to be installed which you've forgotten to
mention in your documentation.
When you are completely satisfied with the quality and accuracy of
your work, forward it to someone else for third-party proofing.
You will be too close to the work to see fundamental flaws.
Have others test the instructions as
well. Make sure they follow exactly what you have written. Ask anyone
who tests your documentation to make specific notes in any places
where they didn't follow your instructions (and the reason why they
didn't follow them). For example: I skipped step 2 because I
already have the required packages installed.
In a sense, editing is like code review in software development.
Having a programmer review their own code doesn't make much sense,
and neither does having a writer edit their own document.
Recruit a friend, or write the discuss list
to find a volunteer to proofread before submitting your document. You
may also want to submit your document to a mailing list that is
relevant to your document's topic. List members should be able to
help check the facts, clarity of your instructions and language of
the document.
If you are writing in a language in which you are not fluent,
find an editor who is. Technical
documentation, more than any other type of writing, must use
extremely precise grammar and vocabulary. Misuse of language
makes your HOWTO less valuable.