# Writing Your Proposal

## Choosing a Subject

It is likely that if you are reading the Author Guide, you already have a subject in mind. The idea may have come from your own frustrations in trying to get something to work; or maybe you are already writing or have written documentation for other purposes and you want to submit it to the LDP. For example, if you posted a question to a mailing list and it took many posts to resolve the problem -- that might be an incentive to write documentation.

Regardless of how you picked your subject, it is important that the LDP community understand why your documentation should be included in its collection. If someone has requested documentation, or you worked with a mailing list to resolve a problem you should include the details in your proposal to the LDP discuss mailing list. It may help others to understand the need for your specific document.

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

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

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

- #### Guides

  A guide covers a broad subject and is quite long. The Author Guide (this document) is a guide. Other guides include: Introduction to Linux: A hands on guide, The Linux Kernel Module Programming Guide, etc. A full list of guides is available from: Linux Project Documentation Guides. Guides use the book templates located in .

- #### 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-HOWTO Module-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 .

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

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

## Unmaintained and Out-of-date Documents

If you wish to become the owner for an unmaintained document there are several steps you must go through.

- Contact the author. Make sure the author no longer wishes to maintain the document in question. Note that the E-mail address shown may no longer be valid. In that case, try a search for the author. If the original author of a document cannot be found after a good-faith effort, let us know (discuss@en.tldp.org--subscription required).

- Determine if a more up-to-date copy of the document exists, outside of what is available on the LDP. If so, try to secure a copy for yourself to work on.

- Inform the LDP which document you would like to maintain, so that we can track who is working on what and prevent duplication of effort. We also suggest that you join the LDP general discussion list (discuss@en.tldp.org). This step is also required for new documents.

- Submit the document to the LDP with any intended modifications. Make sure to continue to reference the original author somewhere within the document (Credits, Revision History, etc.). Once the document is re-submitted, we will remove the entry from the list of unmaintained documents.

### Feedback wanted

Some of unmaintained documents may be outdated, or the content may be covered in another (actively maintained) HOWTO. If that is the situation, contact us (preferably on the discuss mailing list) and let us know.

## Developing an Outline

Before you actually begin writing, prepare an outline. An outline will help you to 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 follow the item before it, and lead into the item that comes next. For example, a HOWTO about a particular program shouldn't have a section on configuration before one on installation.

You may choose to use the following outline for a HOWTO about using a specific program:

- development history

- where to download the software from

- how to install the software

- how to configure the software

- how to use the software

You may find it helpful to try a little card sorting at this stage of the writing process. Write all of your mini subject areas onto pieces of paper. Now sort these pieces of paper into main headings and their sub-sections. It may help to shuffle the slips of paper before you start. This will help to give you a fresh set of eyes while working.

When you are comfortable with your outline, look it over once more, with a critical eye. Have you covered every relevant topic in sufficient detail? Have you not wandered beyond the scope of the document? It is a good idea to show your outline to others (including The LDP discuss list) to get some feedback. Remember: it is much easier to reorganize your document at the outline stage than doing this after writing it.

### Writing a HOWTO made easy

For help writing your HOWTO outline, and getting a head start on the markup of your document, check out The LDP HOWTO Generator. Note that this is for generating HOWTOs. Templates for FAQs and Guides are available in .

### You're not alone

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

## Research

While you are working on your outline you will most likely research your topic--especially to confirm the document you are about to write does not yet exist! Here are a few pointers that will keep you from pulling out your hair later:

- ### Compile your resources as you research.

  It is almost guaranteed you will not remember where to find a critical piece of information when you need it most. It will help to bookmark important (and even not so important) pages as you go. Make sure the bookmark's title reflects why the page is important to you. If there are multiple key ideas in one page, you may want to bookmark the same page with different titles.

- ### Assume your most important resource will disappear.

  The dreaded Error 404: Page not found. Even if you have bookmarked a page it may not be there when you return to it. If a page contains a really critical piece of information: make a copy. You may do this by creating a text file with the title of the document, the author's name, the page's URL and the text of the page into a text file on your computer. You might also choose to print the file to a PDF (save as or convert to PDF format will capture the original URL on the page if you're using a smart browser).

- ### Start your Resources page now.

  As you find pages of interest add them to a Resources document. You may do this by exporting your bookmarks or by keeping a separate text file with the Resources sorted by sub-category. A little effort now will save you a lot of time later.

  There is more information about the DocBook markup of bibliographies in .

- ### Write down subject areas as you go.

  If you are card sorting you may find it particularly useful to write topic cards as you find pages that cover that specific topic. At the top of the card write the subject area. In the main area of the card write a few notes about what you might cover under this topic--include the titles of pages that contain important information. If a sub-topic gets too big you may want to divide it into multiple cards.

- ### Separate generic information from version-specific information.

  A new version of the software that you describe might be released the day after you release your document. Other things, like where to download the software, won't change. Alternatively, you may choose to document old problems with specific software as a way of encouraging readers to upgrade to the latest version available: Version X of the software is known for a specific bug. The bug was fixed as of Version Y.

- ### Save all related emails.

  People will often have interesting insight into the problem that you are writing about. Any questions that are asked about your topic should be addressed in the final document. If you are writing about software make sure to ask people what system they are using. Add information in your document about which system configurations your instructions have been tested on. (Having lots of friends with moderately different configurations can be very beneficial!) All of these personal experiences can add greatly to your final documentation.