4.1. Writing the Text
By now you should have organized your document; you collected bits of raw information and inserted them into the outline. Your next challenge is to massage all of the raw data you've collected into a readable, entertaining and understandable whole. If you are 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 information. Don't be too clever though! Your readers are already struggling with new concepts--do not make them struggle to understand your language as well.
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 . 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:
There are many, many resources for writing web documents--a quick web search for "web writing" will find lots of resources. Don't get too distracted, though: the ultimate goal is to write, not to read about writing!4.1.1. 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 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 it is as close as it gets to an official LDP Style Guide.
 | A personal glossary |
|---|---|
It helps to make a list of terms that you were new to you when you first started researching and writing your document. You can refer to this list while writing the text. You may also want to include it as a glossary in your final document. |
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" to describe your personal experiences and opinions.