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.
The mission of the FreeBSD Documentation Project is to fill this documentation gap. Specifically:
To realize the above goals, the Documentation Project is focused on two specific pieces of documentation:
The goal of the FAQ is to address in a short question and answer format the most common questions that are asked, or should be asked on the various mailing lists and newsgroups devoted to the discussion of FreeBSD. The format does not permit long winded and comprehensive answers.
Topics that need a more in depth discussion than the FAQ can provide are addressed in the FreeBSD Handbook. 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.
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 majordomo@FreeBSD.ORG with a message body of:
subscribe freebsd-doc
(See Mailing lists in the handbook for complete information on the FreeBSD mailing lists.)
We welcome both corrections and additions to existing documentation as well as submissions of entirely new sections. All documents should reflect the state of FreeBSD 2.0.5R 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.
When providing corrections or additions to existing
documentation, the preferred method is context
diff relative to the text as it appears in
- FreeBSD-current. (see the diff(1) manual page
+ FreeBSD-current. (see the diff(1)
+ manual page
for details on generating a context diff). The
FreeBSD-current text for the handbook can be found in:
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/doc/handbook
while the FAQ can be found at:
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/doc/FAQ
Diffs should be directed to freebsd-doc@FreeBSD.ORG for review.
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 handbook and the FAQ and see what you 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.
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 mailing list. A page of Docbook documentation and resources is available to help those interested in learning more.
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.
Some general editorial guidelines: