LDP Author Guide
2004-07-15
Mark
F.
Komarinski
mkomarinski@wayga.org
Jorge
Godoy
Conectiva S.A.
Publishing Department
godoy@metalab.unc.edu
David
C.
Merrill
dcmerrill@mindspring.com
Emma Jane
Hogbin
emmajane@xtrinsic.com
This guide describes the process of submitting and publishing a
document with The Linux Documentation Project (TLDP). It includes
information about the tools, toolchains and formats used by TLDP.
The document's primary audience is new TLDP authors, but it also
contains information for seasoned documentation authors.
4.5
2004-07-14
ejh
Updated information regarding CVS accounts and connecting to the CVS server.
4.4
2004-04-19
ejh
Added editor credit requirements to the Using DocBook
section. Updated the submission procedure. New documents can now only
be added by one of the Review Coordinators after the successful
completion of each of the required reviews.
4.3
2004-04-04
ejh
Removed the section Contributing to The
LDP (replaced by Summary of The LDP Process).
4.2
2004-04-02
ejh
Added references for LyX to DocBook conversions in the
bibliography.
4.1
2004-01-27
ejh
Updated the license requirements and added them to the
table of contents (moved them out of the sub-section).
About this Guide
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.
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 .
LDP Manifesto located at http://www.tldp.org/manifesto.html
The Linux Documentation Project (LDP) is working on
developing free, high-quality documentation for the GNU/Linux
operating system. The overall goal of the LDP is to
collaborate in all of the issues of Linux documentation. This
includes the creation of HOWTOs
and Guides
. We hope to
establish a system of documentation for Linux that will be
easy to use and search. This includes the integration of the
manual pages, info docs, HOWTOs, and other documents.
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 .
This Guide focuses primarily on how to write your own HOWTOs for
submission to the LDP.
Feedback
Send feedback to discuss@en.tldp.org. Please reference the title
of this document in your email. Please note: you must be subscribed
in order to send email to the list.
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.
Acknowledgments and Thanks
Version 1 - Version 3 Thanks
to everyone that gave comments as I was writing this. This includes David
Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig and other
members of the discuss@en.tldp.org list. Some sections I
got from the HOWTO Index
and the sgmltools documentation. The sections on network access to CVS was
partially written by Sergiusz Pawlowicz
(ser@metalab.unc.edu). Sections on DocBook were written by
Jorge Godoy (godoy@conectiva.com). A great deal of thanks
to both of them for their help.
Version 4
Thanks to Tabatha Marshall and Machtelt Garrels (Tille) for making sure I actually
finished the document. Thanks to my reviewers: Charles Curley, Martin
Brown and Tille; and to Saqib Ali for his on-line transformation and
validation tools. I have also incorporated a number of useful emails from the
LDP mailing lists. The original authors are credited within the document.
Special personal thank yous are extended to Steve Champeon for getting me
interested in markup languages and for being a wonderful mentor; and to my
partner, Graig Kent, for being outrageously supportive. [EJH]
Document Conventions
conventions
This document uses the following conventions
Please, take a look at the
source to see how to get
similar results on your documents. You should also remember that
the way this appears to you depends on the format in which you are reading
this document: online appearance is slightly different from the
PostScript or PDF ones.:
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
paraBeginning and end of paragraphpara
Authoring TLDP Documents: An Introduction
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.
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 .
For more information about the mailing lists, please read 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).
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
.
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
.
If you would like to start with a template, you may find the templates in
useful. There is also a general
introduction to markup in and a section
full of examples at .
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 .
If your document is not already in DocBook or LinuxDoc format, a
reviewer will convert it for you.
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 .
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.
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.
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:
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 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.
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 (feedback@en.tldp.org).
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 wantedSome 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 <quote>Resources</quote> 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.
Write
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!
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.
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.
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.
Markup
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 parapara. 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.
DocBook: What it is and why we use it
According to the official DocBook web site,
DocBook.org
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).
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:
,
,
and
from this guide.
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.
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:
Libraries for handling XML files are developing at a
rapid pace. These utilities may make it easier for new
authoring tools to become available.
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.
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
Markup Languages Accepted by TLDP
The LDP stores its documents in the following markup languages:
DocBook XML version 4.2 (preferred), 4.1.2
DocBook SGML version 4.2, 4.1, or 3.x
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.
Distributing Your Documentation
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.
Spelling and Grammar Check
You can read more about helper applications in . You should also check your document for
its overall flow and clarity.
Abstract and Other Meta Data
Add a short paragraph which clearly defines the scope of your
document.
For more information on how to add this information using DocBook
please read
Acknowledgments
Give credit where credit is due. For more information about when to
give credit, read .
License and Copyright
The LDP distributes documents, however, the author maintains the
copyright on the document. All documents accepted by the LDP must
contain a license and copyright notice. You can read more about this
in .
You may also want to add a Disclaimer, but this is optional. More
about this in .
Validate the Markup
If you are submitting a DocBook or LinuxDoc document, make sure the
markup is valid. Read why in .
Obtain Peer Reviews
You may want to have others review your document before
submitting it to the LDP. Ask people for a Peer
Review and/or a Technical
Accuracy Review. Since not all mailing lists will respond favorably
to attachments, you may wish to set up a temporary web site which houses your
document. Note: this is absolutely not required.
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, 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.
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
.
For more information about open source documentation and
licensing, please check .
Copyright
As an author, you may retain the copyright and add other
restrictions (for example: require approval for any translations or
derivative works). If you are a new
maintainer of an already-existing HOWTO, you must include the
previous copyright statements of the previous author(s) and the
dates they maintained that document.
Disclaimer
If you would like to include a disclaimer, you may choose
to use the following:
No liability for the contents of this document can be accepted.
Use the concepts, examples and information at your own risk.
There may be errors and inaccuracies, that could be damaging
to your system. Proceed with caution, and although it is highly
unlikely that accidents will happen because of following advice
or procedures described in this document, the author(s) do not
take any responsibility for any damage claimed to be caused by
doing so.
All copyrights are held by their by their respective owners,
unless specifically noted otherwise. Use of a term in this
document should not be regarded as affecting the validity of
any trademark or service mark. Naming of particular products or
brands should not be seen as endorsements.
Licensing source code
If your HOWTO includes bits of source code that you want others to use,
you may choose to release the source code under GPL.
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
editortag 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 DocBookFor more information on how to add these credits using DocBook
please read
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. 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 .
For more information on what the reviewers will be looking for, please
read the Linux Documentation Project Reviewer HOWTO.
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 at:
Maintaining Your HOWTO
Just because your document has now been published doesn't 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're 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.
Fixing Errors
If you find an error in your own document, please fix it
and re-submit it. You can re-submit your files by emailing
them to submit@en.tldp.org. If you've been
using the CVS, you can simply cvs commit your revised document
and then send an email saying the new version is ready for
distribution. Remember to update the revision history at the
top of the document.
If you find an error in someone else's document please
contact the author of the document, or the LDP
coordinator at feedback@en.tldp.org and
mention the problem and how you think it needs to be
fixed.
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).
References
Markup and general information
Secret Life of Markup, The
SteveChampeon
Progressive Enhancement and the Future of Web Design
Where We Are Now
SteveChampeon
SGML
DocBook References
DocBook XML 4.1.2 Quick Start Guide
JimWeller
Jim Weller
Describes how to install, configure and use the tools and resources for
DocBook XML 4.1.2. The purpose of this quick start guide is to get new
docbook authors, editors, and contributors up and running fast with the
DoocBook tools. These are powerful tool in the hands of an author. It
assumes a fair knowledge of building and installing source packages.
There are probably a million and one ways to accomplish my ultimate
goal of installing and using these tools. This one works well for
me.
Installing And Using An XML/SGML DocBook Editing Suite
Setting Up A Free XML/SGML DocBook Editing Suite For Windows And
Unix/Linux/BSD
Ashley J.S.Mills
2002
The University Of Birmingham
Getting Upto Speed With DocBook
Ashley J.S.Mills
2002
The University Of Birmingham
DocBook: The Definitive Guide
NormanWalsh
LeonardMuellner
1999
O'Reilly & Associates, Inc.
1-56592-580-7
O'Reilly & Associates, Inc.
This book was released by O'Reilly in October 1999, and
is a great reference to DocBook. I have not found it to be a
great practical book. You can pick it up at the book vendor of
choice, and the entire book is also available online (in HTML and SGML
formats) at the above URL.
Simplified DocBook: The Definitive Guide
NormanWalsh
LeonardMuellner
1999
O'Reilly & Associates, Inc.
Simplified DocBook
XML Matters: Getting started with the DocBook XML
dialect
FAQ for DocBook markup
Single-Source Publishing with DocBook XML
DanYork
2002
Dan York
DocBook Install mini-HOWTO
RobertEaster
Exploring SGML DocBook
GiorgioZoppi
LinuxDoc
Howtos-with-LinuxDoc-mini-HOWTO
DavidLawyer
LinuxDoc-SGML User's Guide
Converting Other Formats to DocBook
Converting HTML to Docbook SGML/XML Using html2db
5-Minute Review: Using LyX for Creating DocBook
Document processing with LyX and SGML
LDP templates, tools & links
LDP Templates
http://www.tldp.org/authors/index.html#resources
Contains links to SGML templates and their resulting HTML output
to help you see what your document will look like. Many of the tags
just need to be replaced with information unique to your HOWTO.
Also contains links to tools and other useful information.
Linux Documentation Project HOWTO Generator, The
This is a standalone web page with a number of fields to fill in
and a few buttons. When ready the compile button starts the
compilation of all the input fields and wraps it all in proper
LinuxDoc SGML, ready to process with the LinuxDoc SGML tools.
The compiled output is outputted to a read-only text area near
the bottom of the webpage, so the text has to be copied and
pasted into a file for compilation.
DocBook is not currently supported.
DocBook Transformations
DocBook XML/SGML Processing Using OpenJade
SaqibAli
General Writing Links and Style Guides
Guide to Grammar and Style
JackLynch
Purdue's Online Writing Lab
Chicago Manual of Style
Plain Language Resources
Writing User-Friendly Documents
This is quite useful. It includes before and after writing samples.
PlainTrain Writing Tutorial
Writing for the Web
Information Pollution
Be Succinct! (Writing for the Web)
Politics and the English Language
GeorgeOrwell
A classic text on writing.
Elements of Style, The
Strunk and White
A classic text on writing.
A Short Handbook and Style Sheet
ThomasPinney
Technical Writing Links
Technical Writing Tutorial
Strategies to succeed in technical writing
User Guides Online Tutorial
DMOZ Technical Writing Links
techwr-L
Technical Writing Links
An omnibus of links--scrounge for goodies.
Related TLDP Documents
Linux Documentation Project (LDP) FAQ
RahulSundaram
LDP HOWTO-INDEX
GuylhemAznar
JoshuaDrake
GregFerguson
Software: CVS
CVS: Project Management
ByronClark
CVS
Ashley J.S.Mills
Alan P.Sexton
CVS--Concurrent Versions System
PascalMolli
Learning About CVS
Software: Emacs
Information about PSGML
Emacs: The Free Software IDE
Emacs/PSGML Quick Reference
BobDucharme
NT Emacs Installation
CharlesCurley
Cygwin Packages for DocBook Authoring
SGML for Windows NT
Setting up a free SGML/XML editing and publishing system on
Windows/Cygwin
MarkusHoenicka
2000
Markus Hoenicka
Vim
SteveOualline
XML Authoring Tools
Saqib's list of XML Authoring Tools
Documentation Licenses
Licensing HOWTO
EricRaymond
CatherineRaymond
Eric Raymond and Catherine Raymond
This document explains how U.S. copyright and licensing law applies to
open-source software projects. It compares the strengths and weaknesses of
the existing open-source licenses, and gives guidance on how to choose a
license for your project. It also explains the legalities of changing a
project's license. It suggests new practice for coping with today's
high-threat legal environment--this part is a must-read for all
project leaders.
OPL
OpenContent officially closed June 30, 2003.
Creative Commons
GNU Free Documentation License
GNU General Public License
If you would like your documents to be included in the main Debian
distribution, you should use this license. It is not, however, the
LDP's license of choice.
Templates
The LDP stores its documents in the following markup languages:
DocBook XML version 4.2 (preferred), 4.1.2
DocBook SGML version 4.2, 4.1, or 3.x
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.
Most of the templates are available from the Author
Resources page. There are a few, additional, templates listed
here.
Book Templates
The following templates may be downloaded and used to create your
documents. Documents that are prefixed with a t- were provided by Machtelt Garrels (also known as
Tille, which is pronounced Tilly by the anglophiles). Thanks Tille!
Article <ulink url="http://tldp.org/authors/template/Sample-HOWTO.xml"/>
Most HOWTO documents will use this template.
Book <ulink url="t-book.xml"/>
Use this template to create a full book (like this Author Guide,
for instance).
Appendix <ulink url="t-appendix.xml"/>
Use this template to create an appendix. This list of templates
is an example of an appendix. Note the letters instead of the
numbers which are used to distinguish sections.
Chapters <ulink url="t-chap1.xml"/> and <ulink url="t-chap2.xml"/>
Two sample chapters for book
documents. This template
is not required if you are using the article
template.
Glossary <ulink url="t-glossary.xml"/>
For making glossaries.
FAQ <ulink url="t-faq.xml"/>
A standard article for writing a FAQ (Frequently Asked Questions) list.
Disclaimer <ulink url="disclaimer.xml"/>
A standard disclaimer which warns readers that (1) your document may
not be perfect and (2) you are not responsible if things end up
broken because of it.
Style Sheets
The following style sheets can be used to make your document nicer to
look at. Remember that the LDP will use its own style sheets to
distribute your documentation.
DSL Style Sheet <ulink url="style.dsl"/>
This DSL style sheet was provided by Tille and is to be used with DSSSL
transformations.
Cascading Style Sheet <ulink url="style-ob.css"/>
This CSS file was provided by Saqib Ali and Emma Jane Hogbin. The
ob
is for orange and blue
. Use this CSS
file with an HTML file. Instructions are included in the CSS file.
GNU Free Documentation License
The GFDL (GNU Free Documentation License) is available in XML format
at http://www.gnu.org/licenses/fdl.xml. For a version in appendix format suitable for including
in your document, you can see get the XML for this document
from CVS at http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/fdl-appendix.xml.
TLDP template files for DocBook (XML and SGML) and Linuxdoc SGML are
available from the TLDP website at http://www.tldp.org/authors/index.html#resources.
System Setup: Editors, Validation and
Transformations
In this section, we will cover some of the tools
that you may want to use to create your own LDP documentation.
If you use some other tool to assist you in writing
documents for the LDP, please drop us a line and we'll add
a blurb for it here. has contact
information.