180 lines
7.1 KiB
Text
180 lines
7.1 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
|
|
<!ENTITY date "$Date: 1997-09-28 09:24:31 $">
|
|
<!ENTITY title "FreeBSD Documentation Project">
|
|
<!ENTITY % includes SYSTEM "includes.sgml"> %includes;
|
|
]>
|
|
<!-- $Id: docproj.sgml,v 1.9 1997-09-28 09:24:31 wosch Exp $ -->
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<h2>Goals</h2>
|
|
|
|
<p>Unix has frequently, and rightfully so, been criticized
|
|
for being difficult to learn. While the tool based
|
|
approach to a computing system is powerful, users are often
|
|
stymied by the terse style of the manual pages that
|
|
describe each tool in detail but rarely provide hints about
|
|
how, when or why the tool can be used in day to day
|
|
operations. Many excellent books have been written to show
|
|
the tools in a context and a number are highly recommended
|
|
for anyone using FreeBSD. However, since every Unix system
|
|
has its own quirks, a number of gaps exist in the
|
|
documentation as a whole.</p>
|
|
|
|
<p>The mission of the FreeBSD Documentation Project is to
|
|
fill this documentation gap. Specifically:</p>
|
|
|
|
<ol>
|
|
<li>To cover features, procedures, and other quirks that
|
|
are unique to FreeBSD and thus not to be found in
|
|
commonly available Unix user, administrator and
|
|
programmer guides available on the market. The most
|
|
important of these are:<p></p>
|
|
<ul>
|
|
<li>Installation<p></p></li>
|
|
<li>Hardware support and troubleshooting<p></p></li>
|
|
<li>System configuration and tuning<p></p></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>To provide documentation covering the most commonly
|
|
used aspects of FreeBSD, whether or not the topics are
|
|
covered in other user, administrator and programmer
|
|
guides. This includes topics such as:<p></p>
|
|
<ul>
|
|
<li>Network configuration and troubleshooting<p></p></li>
|
|
<li>ISP services<p></p></li>
|
|
<li>General system administration<p></p></li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
|
|
<h2>Projects</h2>
|
|
|
|
<p>To realize the above goals, the Documentation Project is
|
|
focused on two specific pieces of documentation:</p>
|
|
<ol>
|
|
<li><a href = "FAQ/FAQ.html">The
|
|
FAQ</a></li>
|
|
<li><a href = "handbook/handbook.html">The
|
|
FreeBSD Handbook</a></li>
|
|
</ol>
|
|
|
|
<p>The goal of the <a href =
|
|
"FAQ/FAQ.html">FAQ</a> is to address in a
|
|
short question and answer format the most common questions
|
|
that are asked, or <em>should be</em> asked on the various
|
|
mailing lists and newsgroups devoted to the discussion of
|
|
FreeBSD. The format does not permit long winded and
|
|
comprehensive answers.</p>
|
|
|
|
<p>Topics that need a more in depth discussion than the FAQ
|
|
can provide are addressed in the <a href =
|
|
"handbook/handbook.html">FreeBSD Handbook</a>.
|
|
The current incarnation of the handbook is largely a
|
|
skeletal framework with many empty chapters and sections
|
|
waiting to be filled by words of wisdom.</p>
|
|
|
|
<h2>Contributing to the project</h2>
|
|
|
|
<p>Like the rest of the FreeBSD project, the documentation
|
|
project depends on the tireless contributions of users. To
|
|
facilitate the project, a mailing list has been created for
|
|
the discussion of documentation issues and communication
|
|
among authors. Anyone wishing to contribute to materials
|
|
or editorial time should subscribe by sending mail to <a
|
|
href="mailto:majordomo@FreeBSD.ORG">majordomo@FreeBSD.ORG</a>
|
|
with a message body of:</p>
|
|
|
|
<blockquote>subscribe freebsd-doc</blockquote>
|
|
|
|
<p>(See <a href="handbook/eresources:mail.html">Mailing
|
|
lists</a> in the handbook for complete information on the
|
|
FreeBSD mailing lists.)</p>
|
|
|
|
<p>We welcome both corrections and additions to existing
|
|
documentation as well as submissions of entirely new
|
|
sections. All documents should reflect the state of
|
|
the last release along the FreeBSD -stable branch unless there
|
|
is a compelling reason to cover a different release. In such a
|
|
case, the version to which the information applies must be
|
|
clearly stated.</p>
|
|
|
|
<h3>Submitting corrections</h3>
|
|
|
|
<p>When providing corrections or additions to existing
|
|
documentation, the preferred method is <em>context
|
|
diff</em> relative to the text as it appears in
|
|
FreeBSD-current. (see the <code><a
|
|
href="http://www.freebsd.org/cgi/man.cgi?diff(1)">diff(1)</a>
|
|
</code> manual page
|
|
for details on generating a context diff). The
|
|
FreeBSD-current text for the handbook can be found in:</p>
|
|
|
|
<blockquote><a
|
|
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook</a></blockquote>
|
|
|
|
<p>while the FAQ can be found at:</p>
|
|
|
|
<blockquote><a
|
|
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ</a></blockquote>
|
|
|
|
<p>Diffs should be directed to <a
|
|
href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.ORG</a> for
|
|
review.</p>
|
|
|
|
<h3>Submitting new material</h3>
|
|
|
|
<p>If you can claim expertise on some topic of interest to
|
|
other FreeBSD users and the topic is not covered by either
|
|
the FAQ or the Handbook, we would love to incorporate your
|
|
wisdom into one or the other. If you wish to contribute
|
|
but are not sure what is needed, have a good look through
|
|
the <a href="handbook/handbook.html">handbook</a> and the
|
|
<a href="FAQ/FAQ.html">FAQ</a> and see what
|
|
<em>you</em> think is missing. In particular, the handbook
|
|
has a fairly complete outline but sections marked with an
|
|
asterisk (*) are currently empty and waiting for an eager
|
|
author.</p>
|
|
|
|
<p>At this time, the preferred format for submitting new
|
|
materials is SGML conforming to the Docbook DTD. We are
|
|
actually in the middle of a transition from the Linuxdoc
|
|
DTD to Docbook and details of how source documents get
|
|
turned into other formats is in flux at the moment.
|
|
Announcements regarding this will be made on the freebsd-doc <a
|
|
href="handbook/eresources:mail.html">mailing list</a>. A page of
|
|
<a href="http://fallout.campusview.indiana.edu/~jfieber/docbook">Docbook
|
|
documentation and resources</a> is available to help those
|
|
interested in learning more.</p>
|
|
|
|
<p>If you do not feel comfortable with SGML, the next best
|
|
format is LaTeX because it can be converted to SGML with a
|
|
minimum of hassle. Failing that, plain ASCII submissions
|
|
are always welcome.</p>
|
|
|
|
<p>Some general editorial guidelines:</p>
|
|
|
|
<ul>
|
|
<li>Do not use contractions.<p></p></li>
|
|
|
|
<li>Provide concrete examples.<p></p></li>
|
|
|
|
<li>Use cross references. In the HTML version of the
|
|
document, these become hypertext links.<p></p></li>
|
|
|
|
<li>Do not duplicate other sections of the document, even
|
|
if they have yet to be written. If you feel the existing
|
|
section provides insufficient information to support your
|
|
topic, think about whether the additional information
|
|
should go in the section you are writing, or if it should
|
|
be added to the other end of the cross reference.
|
|
Contact the author of the referenced section if you
|
|
suspect the latter.<p></p></li>
|
|
|
|
</ul>
|
|
|
|
&footer
|
|
</body>
|
|
</html>
|