# Write

## 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:

- Writing for the Web

- Information pollution

- 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. Don't get too distracted, though: 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 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.

### On-line 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 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.

## Tools for Writing, Editing and Maintaining your Document

### Reminder

You do not need to submit your initial document to the LDP in anything more than plain text! Other open submission formats are accepted as well, for instance OpenOffice documents, RTF files or HTML. The LDP volunteers will convert your document to DocBook for you. Once it has been converted you will need to maintain your document in DocBook format, but that should be obvious.

### Editing Tools

You may use any word processing or text editing tool to write your initial document. When you get to the markup stage you may want to use a text editor which recognizes DocBook files. At a minimum a program which adds syntax highlighting to your markup will make life a lot easier. For a description of editors which can handle DocBook files please skip to .

### git

For more information on how to use git to maintain your LDP documents, please read .

### Spell Check

Some writing tools will come with their own built-in spell check tools. This list is only if your application does not have a spell check option.

#### Spell Check Software

aspell

  This spell check application can work around XML tags. By distinguishing between content and markup aspell is able to check your content and ignore the bits it shouldn't be looking at. If you are getting spelling errors in your markup tags you may be using an old version and should upgrade.

  The `aspell` command comes with the aspell package, included on most Linux distributions. Use the command as follows:

      aspell -c file

  An interactive user interface allows for fast and easy correction of errors. Use the `--help` to read more about `aspell` features.

ispell

  Similar to aspell, but tries to spell check your markup tags. If you have a choice, use aspell, if not, ispell is a very acceptable substitute.