The Structure and Writing of HowTos for freebsd-howto.com.

	FreeBSD has a wealth of documentation available. However, unlike
Linux, our Open Source cousin, there are few concentrated sources for this
documentation available. Indeed, the vast majority of knowledge exists in
the realm of mailing list archives, man pages, and source code
documentation. Several sites have attempted to reverse this trend, namely
www.freebsdrocks.com and www.defcon1.org. The FreeBSD project maintains an
informative and largely well-written handbook and FAQ on www.freebsd.org,
however, even this fails at times, as it does not address that vast
diversity of questions and scenarios that the FreeBSD admin is challenged
with in the daily course of administration. There is only one
comprehensive FreeBSD book available, "The Complete FreeBSD" which despite
being an important source for beginners and experienced administrators
alike, it is hardly "complete."

	freebsd-howto.com will attempt to swing this trend by supplying
well written howto manuals on a vast variety of topics. Indeed, we aim to
reach the kind of comprehensive knowledge base that linux-howto.com
embodies. Moreover, we will improve on how linux-howto.com has tackled the
challenge.

	First and foremost the quality and structure of the howtos
supplied must be of excellent quality. Two points on which every howto
must be scrutinized are accuracy and readability. To maintain a sense of
cohension within the site, the structure of each howto will be dictated
shortly. To maintain accuracy, each howto will be reviewed by the
editor/admin of this site. Because he too, is human, and will overlook or
even commit errors now and then, it wil be strongly recommended that the
author submit his/her howto to a third party for review that he/she feels
is knowledgable within the field. Next, each author will be required to
supply contact information on each howto submitted so that readers, upon
suspicion of an error, will be able to notify the author.

	These general considerations having been put forth, let us now
examine the structure that each howto should take in more detail. The top
of each howto will be required to contain the name and two valid emails of
the author, at least one of which should be regularly checked. Below this
a statement concerning the copyright- licensing of the documented must be
presented. Eventhough, under Copyright laws, any originally created
documented is copyrighted by default, we feel that to ensure each author
is given due power over their creation, this should be stated explicitly
and followed by a statement about the licensing rights. Whether the
document is free to be used in any capacity that the human imagination can
fathom, or in a very strict and constricted manner, this should stated
explicitly. Technocrats often fail to give themselves due honour for their
hard work.

	Next, a short, single paragraph summary of what the howto is about
must be supplied. Here is where we must consider the two general classes
of howtos that will be supplied on the site: standard howtos, and mini
howtos. Standard howtos will be aimed at individuals interested in
understanding "why?" in addition to "how?" They will contain a moderate to
heavy amount of background information in addition to the steps necessary
to acheive the general goal of the howto. For instance, a howto on 'PPP in
FreeBSD' will not only explain how to configure user and kernel PPP, but
also how the PPP protocol works, its uses, routing issues, some history,
and so on. It would, in short, not only explain how to configure user or
kernel PPP, but also why PPP "is" in the first place. A mini howto,
however, will not attempt to tackle this latter point, but simply address
the 1 2 3 of configuring PPP in FreeBSD with perhaps some superficial,
cursory information to give the user a "sense" of what is going on. In
essence, mini howtos will be aimed at individuals who are only interested
in getting things working and not in how they work or why they work. This
will be quickly conveyed in the opening summary paragraph. Indeed, howtos
will be organized according to type on the website, however, if an
individual downloads several of them, it will help him/her later in
clearly identifying the nature and intent behind the howtos that had been
downloaded.

	Following this, all howtos will contain a clearly organized table
of contents. Sections will be numbered according to any convention
preferred by the author, and the table of contents will have to break down
the documention into clear sections, each tackling a separate sub-issue. A
simple, but important, part of the howto, the table of contents will allow
users to easily jump to issues discussed within the documention without
necessarily reading it in its entirety.

	The main body that will follow, broken down into sections as
outlined by the table of contents, will have to be clearly written, devoid
of typographical errors, and written in clear, concise language. Not
everyone is the writer of the century, so, soliciting time of friends and
acquaintances to read over youe howto will usually prove to be a valuable
investment. Even if the friend/acquaintance is not familiar with the
topic, a well written howto will "make sense" to him/her such that he/she
would gain a sense of security (if even small) in being able to do what is
explained in the howto and also understand the basics, in the instance a
standard howto. In addition, technical accuracy will be of paramount
importance. If one element has to be sacrified, a little extra readability
will always been less valued than not maintaining complete accuracy and
validity in all technical dialogues within the document. It is heavily
suggested that when references in the body of the howto are made to other
howto documents, such as the FreeBSD Handbook, FAQ, or even other
documents existing on www.freebsd-howto.com, that http addresses be
supplied. Finally, to make the howto an even more effective reference,
all references to FreeBSD commands should be followed by the number of
the man page section. For instance, if a reference is made to the 'ps'
command, it should be written as ps(1). This is especially useful when
there are multiple man pages for a command under different sections,
such as with swapon(2) and swapon(8), where the former is a man page for
the details of the C function swapon(), and the latter is a man page for
the command "swapon"'s use at the command prompt.

	Finally, each howto will be required to end with a quick list of
references that may also be useful to the reader. This will help the
reader, in case the howto does not convey the necessary information, in
looking up further resources that may help him/her. Non-web references
should contain the name of the work, author, copyright date, publisher and
pages referenced. Even references formerly presented in the main body of
the document should be listed in this section, to give the reader a single
point of further references in every doucment. The more information that
can be supplied to the reader, the better he/she is off.
	
	In summary, the following elements must comprise every howto
(standard or mini):

	1) Copyright & License Information
	2) Quick Summary conveying Intent
	3) Table of Contents
	4) Main Body (proofread, with http addresses for references, clear
	   and concise)
	5) Further References (http or comprehensive non-web reference
	   information)

All howtos should be submitted by email to: howto@freebsd-howto.com.
To contact the maintainer of the site, email to: admin@freebsd-howto.com.

Feel free to PGP encrypt HOWTOs with my public key, located in the keyfile:
wms.asc