mirror of https://github.com/tLDP/LDP
445 lines
17 KiB
XML
445 lines
17 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
$Id$
|
|
-->
|
|
|
|
<chapter id="propose">
|
|
<title>Writing Your Proposal</title>
|
|
|
|
<section id="sg-subject">
|
|
<title>Choosing a Subject</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="scope">
|
|
<title>Scope of Your Document</title>
|
|
<para>
|
|
Now that you've got a subject, you will need to decide the
|
|
<emphasis>scope</emphasis> of the document. The scope or subject area
|
|
should be:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Clearly defined.</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Not too broad, and not too narrow.</title>
|
|
<para>
|
|
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 <emphasis>well</emphasis>.
|
|
Similarly, your HOWTO should cover one subject and cover it
|
|
<emphasis>well</emphasis>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Undocumented.</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
If the HOWTO already in place is insufficient or needs updating,
|
|
contact the author and offer to help. See also <xref linkend="unmaintained" /> for taking over old or unmaintained documents.</para>
|
|
|
|
<para>
|
|
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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Pre-approved by the LDP.</title>
|
|
|
|
<para>
|
|
Before you proceed with your HOWTO, post to the discuss list
|
|
and get some feedback from other LDP volunteers. Checking with the
|
|
list <emphasis>before</emphasis> you begin can save you headaches
|
|
<emphasis>later</emphasis>.
|
|
</para>
|
|
|
|
</formalpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<note><title>Stay in touch!</title><para>
|
|
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.
|
|
</para></note>
|
|
|
|
<section id="typesofdocs">
|
|
<!-- Sub-Section added by EJH: August 12, 2003 -->
|
|
<title>Documentation Templates</title>
|
|
<para>
|
|
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 <ulink
|
|
url="http://tldp.org/FAQ/LDP-FAQ/index.html">Linux Documentation
|
|
Project (LDP) FAQ</ulink>. Here is a brief overview of what they are
|
|
with pointers on how you can get started writing your own:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Guides</title>
|
|
<para>A guide covers a broad subject and is quite long. The Author
|
|
Guide (this document) is a guide. Other guides include:
|
|
<ulink
|
|
url="http://tldp.org/LDP/intro-linux/html/index.html">Introduction to Linux: A hands on
|
|
guide</ulink>,
|
|
<ulink url="http://tldp.org/LDP/lkmpg/index.html">The Linux Kernel
|
|
Module Programming Guide</ulink>, etc. A full list of guides is
|
|
available from: <ulink url="http://tldp.org/guides.html">Linux Project
|
|
Documentation Guides</ulink>. Guides use the <quote>book</quote>
|
|
templates located in <xref linkend="templates"/>.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>HOWTOs</title>
|
|
<para>A HOWTO is typically a set of instructions that outlines,
|
|
step-by-step, how a specific task is accomplished. Examples of
|
|
HOWTOs are:
|
|
<ulink url="http://tldp.org/HOWTO/CDROM-HOWTO/index.html">CDROM-HOWTO</ulink>
|
|
<ulink
|
|
url="http://tldp.org/HOWTO/Module-HOWTO/index.html">Module-HOWTO</ulink>.
|
|
A full list of HOWTOs is available from: <ulink
|
|
url="http://tldp.org/HOWTO/HOWTO-INDEX/howtos.html">Single List of
|
|
HOWTOs</ulink> (warning: it's a BIG page). HOWTOs typically use the
|
|
<quote>article</quote> template and are output to multiple HTML
|
|
pages by default.
|
|
Templates are available in <xref linkend="templates"/>.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>man pages</title>
|
|
<para>man (Manual) pages are the standard form of help available for many
|
|
linux applications and utilities. They can be viewed by typing
|
|
<command>man applicationname</command> at a prompt. A full list of man
|
|
pages is available from:
|
|
<ulink url="http://tldp.org/docs.html#man">Linux Man Pages</ulink>.
|
|
Since man pages are bundled with software there is no LDP template
|
|
at this time.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>FAQs</title>
|
|
<para>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: <ulink
|
|
url="http://tldp.org/FAQ/">Linux Documentation Project
|
|
FAQs</ulink>. FAQs typically use the <quote>article</quote>
|
|
template with some specific DocBook elements to form the
|
|
Question/Answer structure.
|
|
You can find a template for writing a FAQ in <xref linkend="templates" />.
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note><title>mini-HOWTOs and HOWTOs</title><para>
|
|
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.
|
|
</para></note>
|
|
|
|
</section> <!-- end of types of docs -->
|
|
</section> <!-- end of choosing a subject -->
|
|
|
|
<section id="unmaintained">
|
|
<title>Unmaintained and Out-of-date Documents</title>
|
|
|
|
<para>
|
|
If you wish to become the <quote>owner</quote> for an unmaintained document there are
|
|
several steps you must go through.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
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 <ulink
|
|
url="http://google.com">search</ulink> for the
|
|
author. If the original author of a document cannot be found after a <quote>good-faith</quote> effort,
|
|
let us know (<email>discuss@en.tldp.org</email>--<ulink
|
|
url="http://tldp.org/mailinfo.html#maillists">subscription
|
|
required</ulink>).
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
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>discuss@en.tldp.org</email>). This step is also required for new
|
|
documents.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
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.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<note><title>Feedback wanted</title><para>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.</para></note>
|
|
|
|
</section>
|
|
|
|
<section id="sg-outline">
|
|
<title>Developing an Outline</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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 <emphasis>configuration</emphasis>
|
|
before one on <emphasis>installation</emphasis>.</para>
|
|
|
|
<para>You may choose to use the following outline for a HOWTO about
|
|
using a specific program:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>development history</para></listitem>
|
|
|
|
<listitem><para>where to download the software from</para></listitem>
|
|
|
|
<listitem><para>how to install the software</para></listitem>
|
|
|
|
<listitem><para>how to configure the software</para></listitem>
|
|
|
|
<listitem><para>how to use the software</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You may find it helpful to try a little <quote>card
|
|
sorting</quote> 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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<tip><title>Writing a HOWTO made easy</title>
|
|
<para>
|
|
For help writing your HOWTO outline, and getting a head start on
|
|
the markup of your document, check out <ulink
|
|
url="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html">The LDP HOWTO
|
|
Generator</ulink>. Note that this is for generating HOWTOs. Templates for FAQs and Guides are available in <xref linkend="templates" />.
|
|
</para></tip>
|
|
|
|
<note><title>You're not alone</title>
|
|
<para>
|
|
You might have noticed a theme developing here.
|
|
Just like Free software, Free documentation is best when you
|
|
<quote>release early, release often.</quote> The discuss list includes
|
|
many experienced LDP authors, and you would be wise to seek their
|
|
advice when making decisions about your contribution.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="research">
|
|
<!-- Section added by EJH: August 12, 2003 -->
|
|
<title>Research</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Compile your resources as you research.</title>
|
|
<para>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.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Assume your most important resource will disappear.</title>
|
|
<para>The dreaded <quote>Error 404: Page not found</quote>. 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 <quote>print</quote> 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).</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Start your <quote>Resources</quote> page now.</title>
|
|
<para>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.</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
There is more information about the DocBook markup of
|
|
bibliographies in <xref linkend="doc-bib" />.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Write down subject areas as you go.</title>
|
|
<para>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.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Separate generic information from version-specific
|
|
information.</title>
|
|
<para>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:
|
|
<quote>Version X of the software is known for a specific bug.
|
|
The bug was fixed as of Version Y.</quote>
|
|
</para>
|
|
</formalpara>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Save all related emails.</title>
|
|
<para>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.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</chapter>
|