mirror of https://github.com/tLDP/LDP
309 lines
13 KiB
XML
309 lines
13 KiB
XML
<!--
|
|
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'>
|
|
-->
|
|
<chapter id="distribute">
|
|
<title>Distributing Your Documentation</title>
|
|
|
|
<section id="pre-distribute">
|
|
<title>Before Distributing Your Documentation</title>
|
|
<para>
|
|
Before you distribute your documentation, there are a few more
|
|
things that you will need to check and possibly add to your document.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Spelling and Grammar Check</term>
|
|
<listitem>
|
|
<para>
|
|
You can read more about helper applications in <xref
|
|
linkend="ag-spellcheck" />. You should also check your document for
|
|
its overall flow and clarity.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Abstract and Other Meta Data</term>
|
|
<listitem>
|
|
<para>
|
|
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 <xref linkend="metadata-markup" />
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Acknowledgments</term>
|
|
<listitem>
|
|
<para>
|
|
Give credit where credit is due. For more information about when to
|
|
give credit, read <xref linkend="crediting-ack" />.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>License and Copyright</term>
|
|
<listitem>
|
|
<para>
|
|
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 <xref linkend="doc-copyright" />.
|
|
You may also want to add a Disclaimer, but this is optional. More
|
|
about this in <xref linkend="doc-disclaimer" />.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Validate the Markup</term>
|
|
<listitem>
|
|
<para>
|
|
If you are submitting a DocBook or LinuxDoc document, make sure the
|
|
markup is valid. Read why in <xref linkend="why-validate" />.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term>Obtain Peer Reviews</term>
|
|
<listitem>
|
|
<para>
|
|
You may want to have others review your document before
|
|
submitting it to the LDP. Ask people for a <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/peerreview.html">Peer
|
|
Review</ulink> and/or a <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html">Technical
|
|
Accuracy Review</ulink>. 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 <emphasis>not</emphasis> required.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="doc-licensing">
|
|
<title>Licensing and Copyright</title>
|
|
<para> In order for a document to be accepted by the LDP,
|
|
it must be licensed and conform to the <quote>LICENSE
|
|
REQUIREMENTS</quote> section of the LDP Manifesto located at <ulink
|
|
url="http://www.tldp.org/manifesto.html">http://www.tldp.org/manifesto.html</ulink>.
|
|
</para>
|
|
|
|
<para> We recommend using the <ulink
|
|
url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation
|
|
License (GFDL)</ulink>, one of the <ulink
|
|
url="http://www.creativecommons.org/license">Creative Commons
|
|
Licenses</ulink> (such as <ulink url="http://creativecommons.org/licenses/by-sa/4.0/">Attribution-Share-Alike</ulink>), 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.</para>
|
|
|
|
<warning>
|
|
<title>Debian-compatible licenses</title>
|
|
<para>The Debian package maintainer for LDP documents has divided the LDP documents into those with a <quote>free</quote> license and those with a <quote>non-free</quote> license. For a summary of this list, please read <ulink url="https://wiki.debian.org/DFSGLicenses">Debian License Summaries</ulink>. Currently the Artistic License, BSD License and the GNU General Public License are listed as <quote>free</quote>. These licenses will also be accepted by the LDP. The definition of <quote>non-free</quote> 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 <emphasis>may</emphasis> be put into the <quote>non-free</quote> package instead of the <quote>free</quote> package. We are working with Debian to clarify how these decisions are made.</para>
|
|
</warning>
|
|
|
|
<para>A DocBook-formatted copy of the license is available in <xref linkend="templates"/>.
|
|
</para>
|
|
|
|
<para>
|
|
For more information about open source documentation and
|
|
licensing, please check <xref linkend="ref-licenses" />.
|
|
</para>
|
|
|
|
<section id="doc-copyright">
|
|
<title>Copyright</title>
|
|
<para>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. </para>
|
|
</section>
|
|
|
|
<section id="doc-disclaimer">
|
|
<title>Disclaimer</title>
|
|
<para>If you would like to include a disclaimer, you may choose
|
|
to use the following:</para>
|
|
<blockquote>
|
|
&disclaimer;
|
|
</blockquote>
|
|
</section>
|
|
|
|
<section id="doc-sourcecode">
|
|
<title>Licensing source code</title>
|
|
<para>If your HOWTO includes bits of source code that you want others to use,
|
|
you may choose to release the source code under GPL.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="crediting-ack">
|
|
<title>Acknowledgments</title>
|
|
|
|
<para>Your document should have an <quote>Acknowledgments</quote> 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.
|
|
</para>
|
|
|
|
<para>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
|
|
<sgmltag class="starttag">editor</sgmltag>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 <emphasis>translators</emphasis>
|
|
and <emphasis>converters</emphasis>.</para>
|
|
|
|
<para>A <emphasis>converter</emphasis> 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.</para>
|
|
|
|
<para>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!</para>
|
|
|
|
<para>
|
|
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.</para>
|
|
|
|
<note><title>Acknowledgments translated in DocBook</title><para>For more information on how to add these credits using DocBook
|
|
please read <xref linkend="metadata-markup" />
|
|
</para></note>
|
|
</section>
|
|
|
|
<section id="ag-review">
|
|
<title>TLDP Review Process</title>
|
|
|
|
<para>
|
|
Before your document is accepted to the LDP collection it will undergo
|
|
at least three formal reviews. These reviews include a <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html">technical accuracy
|
|
review</ulink>, a <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/languagereview.html">language
|
|
review</ulink> and a <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/metadatareview.html">metadata
|
|
review</ulink>. All new documents must pass these reviews
|
|
before being accepted into the collection.
|
|
</para>
|
|
|
|
<para>
|
|
When you feel your document is finished, email a copy to the submit
|
|
mailing list (<email>submit@en.tldp.org</email>). Please include the title of your document and
|
|
<quote>Final Review Required</quote> 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.
|
|
</para>
|
|
|
|
<para>
|
|
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 <ulink
|
|
url="https://github.com/tLDP/LDP">git</ulink> repository to better
|
|
track each of the
|
|
changes that are made, and keep track of the most current version of
|
|
your document.
|
|
</para>
|
|
|
|
<para>
|
|
Once your document has passed both the technical and language reviews,
|
|
you may submit it by following the instructions in <xref
|
|
linkend="submission" />.
|
|
</para>
|
|
|
|
<tip>
|
|
<title>Comparing Two Source Files</title>
|
|
<para>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 <application>XMLdiff</application> 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 <application>diff</application> utility compares text files.</para>
|
|
|
|
<para>XMLdiff is available from <ulink url="http://www.logilab.org/projects/xmldiff" />.</para>
|
|
</tip>
|
|
|
|
<para>
|
|
For more information on what the reviewers will be looking for, please
|
|
read the <ulink
|
|
url="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/index.html">Linux Documentation Project Reviewer HOWTO</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="submission">
|
|
<title>Submission to LDP for publication</title>
|
|
<note><title>The final step</title><para>
|
|
This section contains information on what to do after your
|
|
document has received both a technical and language review by the
|
|
LDP volunteers.
|
|
</para></note>
|
|
|
|
<para>
|
|
As part of the review process a Review Coordinator will add your
|
|
document to github (including any associated image files) and
|
|
notify the submit mailing list that your document is ready for
|
|
publication.
|
|
</para>
|
|
|
|
<!--
|
|
|
|
<para> Once your LDP document has been carefully reviewed, you
|
|
can release your document to the LDP. Send an e-mail with the
|
|
source code as an attachment (you may gzip it if you like)
|
|
to <email>submit@en.tldp.org</email>. </para>
|
|
|
|
<para> Be sure to include the name of your work in the subject
|
|
line, and use the body to outline changes you've made and attach
|
|
your document's source code. This allows the maintainers to do their jobs faster, and
|
|
means your revised document will appear on the site faster.
|
|
If you haven't heard anything in 5 calendar days,
|
|
please follow up with an e-mail to make sure things are still in
|
|
process. </para>
|
|
|
|
<para>If your text contains extras, such as graphics or a
|
|
special catalog, create a .tar.gz file with all the files in it,
|
|
including the XML source code, and mail it as an attachment to
|
|
the submit list.</para>
|
|
|
|
<para>If you are using the LDP CVS tree while developing
|
|
your document, the LDP will still need to be notified when your
|
|
document is ready to be published. E-mail should be sent to
|
|
<email>submit@en.tldp.org</email>. Indicate
|
|
the title of your document and the relative path to the
|
|
file(s) in the LDP CVS tree within your message. </para>
|
|
|
|
<para> To get a CVS account please refer to: <ulink
|
|
url="http://tldp.org/cvs/">http://tldp.org/cvs/</ulink>
|
|
</para>
|
|
</section>
|
|
<section id="compilations">
|
|
<title>Publishing Compilations of LDP Documents</title>
|
|
<para>
|
|
If you are interested in publishing a collection of
|
|
LDP documents, please visit <ulink
|
|
url="http://www.tldp.org/manifesto.html#pub">http://www.tldp.org/manifesto.html#pub</ulink>
|
|
for more information.
|
|
</para>
|
|
</section>
|
|
-->
|
|
</section>
|
|
</chapter>
|