4.2. 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 does not 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 content of every section matches the title
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 new machine. Sometimes there
are packages that need to be installed which you've forgotten to
mention in your documentation, for instance.
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.
 | Native speaker? |
|---|
| |
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 document less valuable.
|
jamesthornton.com>