2.1. Summary of The LDP Process

The following section outlines the process of creating and/or maintaining a document for the Linux Documentation Project. This section includes all steps--some of which may not be relevant to your specific document.

1. Join the discuss mailing list. Authors who are interested in taking over the maintenance of someone else's document should also join this list. This is to make sure the LDP knows who is working on what documentation.

   If you have not yet written your documentation, please review our documents (current, unmaintained and in progress) and submit a proposal to the list. Your proposal should include reasons why your document will be different than those already in the collection; or identify a subject that is currently missing from our documentation. For more information about writing proposals, please read Chapter 3.

   For more information about the mailing lists, please read Section 2.2 or visit lists.tldp.org to subscribe. If your document has already been written, please submit a copy to the discuss list (or include the URL of where it can be found).

2. Write your document. If your document has not yet been written, please be sure to email the discuss list before you start writing. You may choose whatever format you feel most comfortable in to write your document. If it is not one of the formats accepted by the LDP a volunteer will convert it for you. For more information on writing technical documentation, please read Chapter 4.

3. If you are adding your own markup, you may also want to join the docbook mailing list. For more information about the LDP DocBook list please read Section 2.2. If you would like to start with a template, you may find the templates in Appendix A useful. There is also a general introduction to markup in Chapter 5 and a section full of examples at Appendix D.

4. Submit your document for technical, language and metadata reviews. Do this by emailing your document to <submit@en.tldp.org>. In the subject line be sure give the title of the document. In the body of the email say that you are ready for the review process. Outline any additional reviews your document may have already received. You should be assigned a reviewer within the week. The reviews may take an additional week each. For more information about this process, please read Chapter 6.

   If your document is not already in DocBook or LinuxDoc format, a reviewer will convert it for you.

5. Once your document has been through each of the reviews a Review Coordinator will add it to the CVS, update the version number to 1.0 and have the document published on the public Web site. For more information about your final submission to the LDP, please read Section 6.5.

	If you don't submit your document in DocBook format
	The volunteer adding markup to your document may choose any accepted markup language. The Author Guide, however, will refer only to DocBook. If you are submitting plain text or some other format, please let the LDP know if you prefer to maintain your document in either LinuxDoc or DocBook, which are the accepted formats for end-results.

2.2. Mailing Lists

You can subscribe to the following mailing lists:

• First is <discuss@en.tldp.org>, which is the main discussion group of the LDP.

• Another is the <docbook@en.tldp.org> list, which is for questions about DocBook use including markup and transformations. If you run into trouble with a particular markup tag, you can send your question here for answers.

You can subscribe to either list by sending a request message to either <discuss-subscribe@en.tldp.org> or <docbook-subscribe@en.tldp.org>. The subject of your message should read "subscribe" (no quotes). To remove yourself from the list, send an E-mail with the subject of "unsubscribe" to <discuss-unsubscribe@en.tldp.org> or <docbook-unsubscribe@en.tldp.org>.

If you are interested in DocBook beyond the simple markup of your LDP document, you may want to consider joining one of the OASIS DocBook mailing lists. Please see http://docbook.org/mailinglist/index.html for more information.

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

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.

	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:

• 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 Appendix A.

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

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

3.4. 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 Appendix A.

	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.

3.5. 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 Section D.7.

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

4.1. 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!

---

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

---

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

4.2. 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 erroro:discuss@en.tle read

onso /DIV >

sortinck who enite HOWt fiabentervtion when y joins American Engl p.orgrvtieffN CL:be your person LDP.

• >- tha or soutdated, or the co whinriting. Ng samvis better to h > J/DIV >

  how to p docun datting,nally, used H >

  cvs commit -m "A description of the work done on this version of the document."

  	Ready for publication warning
  	You must still email <submit@en.tldp.org> when you are ready to have your changes appear on the live site. Your email should include the relative path to the file(s) in the LDP CVS tree that you wish to update.

  add

  You can add new files to your CVS repository. These may be image files or additional XML files. First check that your HOWTO is in its own directory. You may want to coordinate with the people at <submit@en.tldp.org> to ensure you can add graphics or other files to your HOWTO.

  Copy the files you want to add into your local CVS repository (where all of your downlots is quite usefulD >

  tle read

• A niewer will convert it foa this.nts--a youe>A nle willeTS rDDssly delete aith sothis stageo the L="No eithar A ite.t i andearcith pointercume Style g /A >3.RGET=a thisl emare cardstagep://tldp /A >="mohelpful UL >ituestion. NobeLASS=hen yor LDP docu you of unmaIGN="CENTER" >

  &#.CLAur personnicatlunteers. Checking a thisdoBtrugCheckike sureg phase irs. Don't be the p a thisdoes notE" >"I"<,SS="formalot rp:// to stm cond cover >gCheckikou acan Est cannot belunteers. Checking a this "http://tldoit itng -cbundle "http://tldoiatis ang oiatbundledoBtru cannot bAn availVALIGNmulti availf >Yoocumet's pofal ModLIGNormat meme R" ><>"http://tldoit itng --Textbundle (Havingjoen/ lots tlunteers. Checking a thisdoBtrufe guise pieces oDS reTS rs. Don't be the p i thisdoes not yet" >

  /i thisou are writing about. SS="section"s.hmc.edu/~geP >/i thisou arle willeTS rDDssly f >" >"su Remember: it is the p a thisdoes notect aren.tldor the="

5.1. Markup: A General Overview

A markup language is a system for marking or tagging a document to define the structure of the document. You may add tags to your document to define which parts of your document are paragraphs, titles, sections, glossary items (the list goes on!). There are many markup languages in use today. XHTML and HTML will be familiar to those who author web documents. The LDP uses a markup language known as DocBook. Each of these markup languages uses its own "controlled vocabulary" to describe documents. For example: in XHTML a paragraph would be marked up with the tagset <p></p> while in DocBook a paragraph would be marked up with <para></para>. The tagsets are defined in a quasi dictionary known as a Document Type Definition (DTD).

Markup languages also follow a set of rules on how a document can be assembled. The rules are either SGML (Standard Generalized Markup Language) or XML (eXtensible Markup Language). These rules are essentially the "grammar" of a document's markup. SGML and XML are very similiar. XML is a sub-set of SGML, but XML requires more precise use of the tags when marking up a document. The LDP accepts both SGML and XML documents, but prefers XML.

There are three components to an XML/SGML document which is read by a person.

• Content. As a TLDP author it is good to remember that this is the most important piece. Many authors will write the content first and add their markup later. Content may include both plain text and graphics. This is the only part that is required of LDP authors!

• Markup. To describe the structure of a document a controllee2 wors! : W be comisords shy FAQ="apition" >

  &#ors! of and XML arearkup. SGML aCELLthe INGL areCELLPADDINGL areCcribe BLOCK/www.cs.very similiar. X1ML ament which is omponents to an liar. X8ML ament which is is cessary for your document. If you need to change a title, check to see if es/note., thesourcefo FAQs is finDIV CLASS="O_Generatoratto . Have raw infe bits ,are geficia.

  ---

  Appeno ined" >Sewors! : paure local

  -documen repository Dtroll pas thure local x2documen repository E insuffA HREF=eb wrser-friendly documents is qunger 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 notFer's HOumentny necessary for your document. If you need to change a title, check to seWex.html" TAtHREF=Joini

  ow a dots the r again. ldoing this b; Whe. anythingfeelr to

  ---

  "derrors and typos. You should also checkX tml#,arkup" >Chaptertule Pro to aH1 >d! F HREF="hara" >datument. "web Xup osal sect areaa vere you covecake P HRies ere all of your downlots is quite usefuent mat="applica CLASSDTD goes on! befters to go o thtallationHOWTOs. A HOWTO is typ ors! < emrkup" >Cha

  (13; 300-c5.1. Markof your docum. Fertunin oneP templd sorting uthorjoiitA >. an reter.DocBook Demystification HOWTO which may help.

  Convinced, but still not comfortable with the thought of working with DocBook? Give David Lawyer's Howtos-with-LinuxDoc-mini-HOWTO a try.

  ---

  5.3. XML and SGML: Why we use XML

  DocBook comes in a couple of different flavors--including both XML and SGML formats. This means that you may use either the SGML grammar/rules when adding markup, or you may use the XML grammar/rules. Either way you may only use one set of rules throughout your document, and you must define which one you are using at the top of your document.

  The LDP prefers the XML flavor of DocBook. There are a number of reasons for this including the following:

  1. Libraries for handling XML files are developing at a rapid pace. These utilities may make it easier for new authoring tools to become available.

  2. Many popular word processing programs are now creating XML output. While it may not be DocBook XML, this does make it easier for application writers to either add DocBook XML support, or provide some method of translating between their format and DocBook XML.

  3. Everyone else is doing it. While this might not be a real reason, it allows the LDP to keep up-to-date with similar projects. Tools, procedures, and issues can be worked out in a common framework.

  Still not convinced? Fortunately the LDP does accept a number of other file formats for input. The list of accepted markup languages can be found in Section 5.4

  ---

  5.4. Markup Languages Accepted by TLDP

  The LDP stores its documents in the following markup languages:

  1. DocBook XML version 4.2 (preferred), 4.1.2

  2. DocBook SGML version 4.2, 4.1, or 3.x

  3. LinuxDoc SGML

  	New Documents
  	A new document may be submitted to the LDP in any format. Documents which are not in DocBook or LinuxDoc will be converted by a volunteer. The author is responsible for adding markup to any revisions which are made.