1.1. About this Guide

This document was started on Aug 26, 1999 by Mark F. Komarinski after two day's worth of frustration getting tools to work. If even one LDP author is helped by this, then I did my job.

Version 4 of this document was released in early 2004 by Emma Jane Hogbin. A complete overhaul of the document was done to separate the authoring HOWTOs from the technical HOWTOs. The review took approximately eight months.

The newest version of this document can be found at the LDP homepage http://www.tldp.org. The original DocBook, HTML, and other formats can be found there.

There are many ways to contribute to the Linux movement that do not require the ability to produce software. One such way is to write documentation. The availability of easy-to-understand, technically accurate documentation can make a world of difference to someone who is struggling with Linux software. This Guide is designed to help you research and write a HOWTO which can be submitted to the LDP. The appendices also include sample templates, markup tips and information on how to transform your document from DocBook to another format (such as HTML) for easier proofreading.

1.2. About The LDP

The Linux Documentation Project (LDP) was started to provide new users a way of quickly getting information about a particular subject. It not only contains a series of books on administration, networking, and programming, but also has a large number of smaller works on individual subjects, written by those who have used it. If you want to find out about printing, you get the Printing HOWTO. If you want to do find out if your Ethernet card works with Linux, grab the Ethernet HOWTO, and so on.

The LDP provides documents to the world in a variety of convenient formats and also accepts submissions in a number of formats. The current standard for storing the source documentation is a format known as DocBook, see Section 5.2.

The human readable version goes more like this: The LDP consists of a large group of volunteers who are working on documentation about Linux and the programs which run on the Linux kernel. These documents exist primarily as shorter HOWTOs and longer Guides. Both are available from http://www.tldp.org/. This Guide focuses primarily on how to write your own HOWTOs for submission to the LDP.

1.3. Feedback

Send feedback to <[email protected]>. Please reference the title of this document in your email. Please note: you must be subscribed in order to send email to the list.

1.4. Copyrights and Trademarks

Copyright 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the appendix entitled "GNU Free Documentation License."

1.5. Acknowledgments and Thanks

1.6. Document Conventions

This document uses the following conventions[1]:

Descriptions	Appearance
Information requiring special attention	This is a warning.
Caution	This cautions the reader.
Hint	This is a hint.
Notes	This is a note.
File Names	file.extension
Directory Names	directory
Commands to be typed	command
Applications Names	application
Prompt of users command under bash shell	bash$
Prompt of root users command under bash shell	bash#
Prompt of user command under tcsh shell	tcsh$
Environment Variables	VARIABLE
Emphasized word	word
Quoted text	"quote"
Code Example	<para>Beginning and end of paragraph</para>

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 <[email protected]>. 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 <[email protected]>, which is the main discussion group of the LDP.

• Another is the <[email protected]> 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 <[email protected]> or <[email protected]>. 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 <[email protected]> or <[email protected]>.

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 (<[email protected]>--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 (<[email protected]>). 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)

---

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.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 errors as well, such as "holes" in the information. If you are creating a set of instructions it may help to test them on a new machine. Sometimes there are packages that need to be installed which you've forgotten to mention in your documentation, for instance.

When you are completely satisfied with the quality and accuracy of your work, forward it to someone else for third-party proofing. You will be too close to the work to see fundamental flaws. Have others test the instructions as well. Make sure they follow exactly what you have written. Ask anyone who tests your documentation to make specific notes in any places where they didn't follow your instructions (and the reason why they didn't follow them). For example: "I skipped step 2 because I already have the required packages installed."

In a sense, editing is like code review in software development. Having a programmer review their own code doesn't make much sense, and neither does having a writer edit their own document. Recruit a friend, or write the discuss list to find a volunteer to proofread before submitting your document. You may also want to submit your document to a mailing list that is relevant to your document's topic. List members should be able to help check the facts, clarity of your instructions and language of the document.

	Native speaker?
	If you are writing in a language in which you are not fluent, find an editor who is. Technical documentation, more than any other type of writing, must use extremely precise grammar and vocabulary. Misuse of language makes your document less valuable.

4.3. Tools for Writing, Editing and Maintaining your Document

	Reminder
	You do not need to submit your initial document to the LDP in anything more than plain text! Other open submission formats are accepted as well, for instance OpenOffice documents, RTF files or HTML. The LDP volunteers will convert your document to DocBook for you. Once it has been converted you will need to maintain your document in DocBook format, but that should be obvious.

---

4.3.2. Concurrent Versions System (CVS)

The LDP provides optional CVS access to its authors. This enables collaborative writing and has the following positive effects:

1. CVS will keep an off-site backup of your documents. In the event that you hand over a document to another author, they can just retrieve the document from CVS and continue on. In the event you need to go back to a previous version of a document, you can retrieve it as well.

2. However difficult from an organizational point of view, it's great to have multiple people working on the same document. CVS enables you to do this. You can have CVS tell you what changes were made by another author while you were editing your copy, and integrate those changes.

3. CVS keeps a log of what changes were made. These logs (and a date stamp) can be placed automatically inside your documents when they are published.

4. CVS can be combined with scripts to automatically update the LDP web site with new documentation as it's written and submitted. This is not in place yet, but it is a goal. Currently, CVS updates signal the HOWTO coordinator to update the LDP web page, meaning that if you use CVS, you're not required to e-mail your XML code. (Although you do still need to send the submit list an email when you are ready for your document to be published, because the whole publishing process has not been fully automated yet.)

	Access to our CVS repository
	Only authors with at least three submissions get access to our CVS, see Appendix C.

For more information on how to use CVS to maintain your LDP documents, please read Appendix C.

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 controlled vocabulary is added on top of the content. It is used to distinguish different kinds of content: paragraphs, lists, tables, warnings (and so on). The markup must also conform to either SGML or XML rules. If you are not comfortable adding markup to your document, a TLDP volunteer will do it for you.

• Transformation. Finally the document is transformed from DocBook to PDF, HTML, PostScript for display in digital or paper form. This transformation is controlled through the Document Style Semantics and Specification Language (DSSSL). The DSSSL tells the program doing the transformation how to convert the raw markup into something that a human can read. The LDP uses a series of scripts to automate these transformations. You are not required to transform your own documents.

	Content, markup and transformations
	Steve Champeon does a great job of explaining how content, markup languages, and transformations all fit together in his article The Secret Life of Markup. Although he is writing from an HTML perspective, the ideas are relevant and there is an example of DocBook markup.

5.2. DocBook: What it is and why we use it

According to the official DocBook web site,

	DocBook is a general purpose XML and SGML document type particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).
--DocBook.org

	For the impatient
	In the next sections we will be explaining about the theoretical side of DocBook, its origins, development, advantages and disadvantages. If you just want the practical side, check out these sections for an overview of HOWTO DocBook: , Appendix D, and Appendix E from this guide.

For the beginner

We wish to stress again the fact that any open document format will be accepted. If you feel more comfortable with plain text, OpenOffice or HTML, that is fine with us. If you do not look forward to learning DocBook, LDP volunteerd will convert your document to DocBook XML. To us, the most important task for our authors is the actual writing, not the formatting, keep that in mind! From the point of submission onwards, however, you will have to maintain your document in this XML format, but that's a piece of cake. Promised.

Although there are other DTDs used to write documentation, there are a few reasons not to use them.

• DocBook is the most popular DTD, being used by more than a dozen major open source projects from GNOME to Python to FreeBSD.

• The tools for DocBook are more developed than others. DocBook support is included in most Linux distributions, allowing you to send raw files to be processed at the receiver's end.

• And finally, DocBook has an extensive set of tags (over 300 in all) which is very useful when you are trying to describe the content of a document. Fortunately for new authors the majority of them do not need to be used for simple documentation.

Still not convinced? Eric Raymond has written a 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.

6.1. Before Distributing Your Documentation

Before you distribute your documentation, there are a few more things that you will need to check and possibly add to your document.

6.2. Licensing and Copyright

In order for a document to be accepted by the LDP, it must be licensed and conform to the "LICENSE REQUIREMENTS" section of the LDP Manifesto located at http://www.tldp.org/manifesto.html.

We recommend using the GNU Free Documentation License (GFDL), one of the Creative Commons Licenses (Share-Alike, or Attribution-Share-Alike), or the LDP license (currently under review). The full text of the license must be included in your document, including the title and version of the license you are using. The LDP will not accept new documents that do not meet licensing requirements.

Debian-compatible licenses

The Debian package maintainer for LDP documents has divided the LDP documents into those with a "free" license and those with a "non-free" license. For a summary of this list, please read Debian License Summaries. Currently the Artistic License, BSD License and the GNU General Public License are listed as "free". These licenses will also be accepted by the LDP. The definition of "non-free" has not been made transparent. By choosing another license that has any kind of restriction on redistribution or whether or not the document may be modified, your document may be put into the "non-free" package instead of the "free" package. We are working with Debian to clarify how these decisions are made.

You can get DocBook markups of both the GNU GPL and the GNU FDL from the GNOME Documentation Project. You can then merely include the license in its entirety in your document. A DocBook-formatted copy of the license is available in Appendix A.

For more information about open source documentation and licensing, please check .

6.3. Acknowledgments

Your document should have an "Acknowledgments" section, in which you mention everyone who has contributed to your document in any meaningful way. You should include translators and converters, as well as people who have sent you lots of good feedback, perhaps the person who taught you the knowledge you are now passing on, and anybody else who was instrumental in making the document what it is. Most authors put this section at the end of their document.

When someone else assists in the production of an LDP document, you should give them proper attribution, and there are DocBook tags designed to do this. This section will show you the tags you should use, as well as other ways of giving credit where credit is due. Crediting editors is easy - there is already an <editor>tag in DocBook. But there are two special cases where you need to credit someone, but DocBook doesn't provide a special tag. These are translators and converters.

A converter is someone who performs a source code conversion, for instance from HTML to DocBook XML. Source code conversions help the LDP achieve long term goals for meta-data, and allow us to distribute documentation in many different formats.

Translators take your original document and translate it into other human-readable languages, from English to Japanese for example, or from German to English. Each translation allows many more people all over the world to make use of your document and of the Linux operating system!

We recommend that you acknowledge converters in the comment for the initial version released in the new format, and we recommend that you credit translators in each version which they have translated.

	Acknowledgments translated in DocBook
	For more information on how to add these credits using DocBook please read Section D.6

6.4. TLDP Review Process

Before your document is accepted to the LDP collection it will undergo at least three formal reviews. These reviews include a technical accuracy review, a language review and a metadata review. All new documents must pass these reviews before being accepted into the collection.

When you feel your document is finished, email a copy to the submit mailing list (<[email protected]>). Please include the title of your document and "Final Review Required" in the subject line of your email. A team of volunteers will be assigned to your document for each of the reviews. It may take up to a week to gather a team who is qualified to review your document. Typically the technical review happens first, followed by the language review and finally the metadata review. Your reviewers will read your document give you feedback on whether or not they think your document is ready for publication in the LDP collection.

Your reviewers may have specific points that must be changed. Once you have made the changes submit your document back to your review team. They will review the document again and advise you on whether or not your document is ready for inclusion in the LDP collection. You may need to undergo several edits before your document is ready. Or it may not require any additional work. Be prepared to make at least one round of changes for both the technical and language reviews. Ideally this exchange will happen in the LDP's CVS to better track each of the changes that are made, and keep track of the most current version of your document.

Once your document has passed both the technical and language reviews, you may submit it by following the instructions in Section 6.5.

Comparing Two Source Files

Your reviewer may make changes directly to your source file, or they may put their suggestions in a separate email. If they are working with the source file directly, and your document is using DocBook XML, you may find XMLdiff useful to see the changes that your reviewer has made to your source file. It is a python tool that figures out the differences between two similar XML files, in the same way the diff utility compares text files. XMLdiff is available from http://www.logilab.org/projects/xmldiff.

For more information on what the reviewers will be looking for, please read the Linux Documentation Project Reviewer HOWTO.

6.5. Submission to LDP for publication

	The final step
	This section contains information on what to do after your document has received both a technical and language review by the LDP volunteers.

As part of the review process a Review Coordinator will add your document to the CVS (including any associated image files) and notify the submit mailing list that your document is ready for publication.

If you do not already have a CVS account, please apply for one when your document is submitted for publication. You can apply for an account contacting LDP CVS master Sergiusz mailto:[email protected]

7.1. Maintaining Your Document

Just because your document has now been published does not mean your job is done. Linux documentation needs regular maintenance to make sure it is up to date, and to improve it in response to readers' ideas and suggestions. TLDP is a living, growing body of knowledge, not just a publish-and-forget-it static entity.

Add relevant mailing lists to your document where people can get support. If you have the time, follow these mailing lists yourself to stay up-to-date on the latest information.

Put your email address in the document, and politely request feedback from your readers. Once you are officially published, you will begin to receive notes with suggestions. Some of these emails will be very valuable. Create a folder in your mail program for incoming suggestions--when the time is right review the folder and make updates to your document. If you are following a related mailing list you may also choose to save a copy of important emails from the list to this folder.

	We are not a free support service, but...
	Some people who email you will request personal assistance. You should feel free to decline personal assistance if you cannot spare the time. Writing a contribution to the LDP does not commit you to a lifetime of free support for anyone on the net; however, do try to reply to all requests and suggest a mailing list that will (hopefully) be able to provide support to your reader.

7.2. Fixing Errors

---

7.2.2. Fixing Other Documents in the Collection

If you find an error in someone else's document please contact the author of the document with the correction. If you do not hear back from the author within a "reasonable" amount of time, please email the LDP coordinator at <[email protected]> (subscription required) and describe the problem and how you think it needs to be fixed. If the license permits, you may be asked to make the change directly to the document. If the problems are serious, the document may be removed from the collection, or moved to the "Unmaintained" section.

	Taking over unmaintained documentation
	For more information on how to deal with unmaintained documents, please read: Unmaintained (includes a list of steps to take to take over "ownership" of unmaintained documents, and a list of unmaintained documents).