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.