3.2. Scope of Your Document

Now that you've got a subject, you will need to decide the scope of the document. The scope or subject area should be:

  1. Clearly defined. Define the boundaries of your subject area before you begin. Do not repeat information that is in another HOWTO and do not leave gaps of information between your HOWTO and someone else's HOWTO.

  2. Not too broad, and not too narrow. If you try to cover too much information you may sacrifice depth. It is better to cover a small subject area in detail than to cover a large subject area poorly. Linux tools are known for doing exactly one thing and doing that one thing well. Similarly, your HOWTO should cover one subject and cover it well.

    If the scope of your proposed document is very narrow, it might be better to include your information as part of another HOWTO. This makes it easier for readers to find the HOWTO they need. Search the LDP repository for topics which relate to your document. If you find a document which is a good match, email the author and ask them if they would like to include your contribution.

  3. Undocumented. Before documenting a particular subject, always do a web search (and specifically a search within the LDP documents) to see if your topic is already covered in another document. If it is, refer to the other document instead of duplicating the information within your own document. You may wish to include a brief summary of information that can be found in other documents.

    If the HOWTO already in place is insufficient or needs updating, contact the author and offer to help. See also Section 3.3 for taking over old or unmaintained documents.

    Most authors appreciate any help offered. Additionally, sending comments and remarks to the author is usually regarded both as a reassurance and a reward: to the author, feedback is the ultimate proof that writing the documentation was not a pointless effort.

  4. Pre-approved by the LDP. Before you proceed with your HOWTO, post to the discuss list and get some feedback from other LDP volunteers. Checking with the list before you begin can save you headaches later.

NoteStay in touch!

Joining the discuss list and following it regularly, even if you never post, is a good way to stay current on the activities, needs and policies of the LDP.

3.2.1. Documentation Templates

After you've decided the scope of your document you should start to consider the type of document that you will write. There are a number of different LDP documentation templates: Guides, HOWTOs, man pages and FAQs. Rahul Sundaram describes their scope in the Linux Documentation Project (LDP) FAQ. Here is a brief overview of what they are with pointers on how you can get started writing your own:

Notemini-HOWTOs and HOWTOs

The LDP no longer distinguishes between HOWTOs and mini-HOWTOs. All previously written mini-HOWTOs have been included in longer HOWTOs. All new documents must be at least HOWTO in length. This means the documents should cover a bigger subject area rather than a small one. If your document is very small you may wish to submit it for inclusion in another, larger HOWTO that already exists. If you're not sure what size your document is, email the discuss list and ask for feedback.