5.2. Developing an Outline

Before you actually begin writing, prepare an outline. An outline will help you get a clear picture of the subject matter, and allow you to concentrate on one small part of the HOWTO at a time.

Unless your HOWTO is exceptionally small, your outline will probably be multilevel. When developing a multilevel outline, the top level should contain general subject areas, and sub-headings should be more detailed and specific. Look at each level of your outline independently, and make sure it covers all key areas of the subject matter. Sub-headings should cover all key areas of the heading under which they fall.

Each item in your outline should logically follow the item before it, and lead into the item it precedes. For example, a HOWTO about a particular program shouldn't have a section on configuration before one on installation.

When you are comfortable with your outline, look over it once more, with a critical eye. Have you covered every relevant topic in sufficient detail? Have you wandered beyond the scope of the HOWTO? You might want to show it to someone else, and ask for feedback. It's much easier to reorganize your HOWTO at the outline stage than it will be later. Consider submitting the outline to the ldp-discuss list for more feedback.

Note

You might have noticed a theme developing here. Just like Free software, Free documentation is best when you "release early, release often." The ldp-discuss list includes many experienced LDP authors, and you would be wise to seek their advice when making decisions about your HOWTO.

Remember Linus' Law:

 

"Given enough eyeballs, all [typos] are shallow."

 
--Eric S. Raymond 

(With apologies to Mr. Raymond.)

FIXME: Need a reference to the "standard" HOWTO layout, for topic areas such as Credits, License, Copyright, etc., etc.