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:

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.

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.

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.

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.

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

HOWTOs. A HOWTO is typically a set of instructions that outlines,
step-by-step, how a specific task is accomplished. Examples of
HOWTOs are:
CDROM-HOWTOModule-HOWTO.
A full list of HOWTOs is available from: Single List of
HOWTOs (warning: it's a BIG page). HOWTOs typically use the
"article" template and are output to multiple HTML
pages by default.
Templates are available in Appendix A.

man pages. man (Manual) pages are the standard form of help available for many
linux applications and utilities. They can be viewed by typing
man applicationname at a prompt. A full list of man
pages is available from:
Linux Man Pages.
Since man pages are bundled with software there is no LDP template
at this time.

FAQs. FAQs (Frequently Asked Questions) are a list of questions and
answers to help prevent new users from asking the same questions
over and over again.
A full list of FAQs is available from: Linux Documentation Project
FAQs. FAQs typically use the "article"
template with some specific DocBook elements to form the
Question/Answer structure.
You can find a template for writing a FAQ in Appendix A.

mini-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.