## Find appropriate documentation ##

[Author](authors.html): [[KevinDKinsey]]

[Reviewer](technical_reviewers.html): _name_ _[[contact]]_ _[[BSD_flavour]]_

[Reviewer](technical_reviewers.html): _name_ _[[contact]]_ _[[BSD_flavour]]_

----



### Concept ###

* Understand that BSD systems are well documented and there are many detailed resources
available to a system administrator. 
* Be able to use the documentation(((documentation))) found on the system
itself as well as be aware of the resources available on the Internet.


TODO: there is another section about this, so need to make sure they are not covering same details.
TODO: if one section should be removed, we can just merge the concept and content together
TODO: [[Recognize_the_different_sections_of_the_manual]]


### Introduction ###

Some people say BSD systems "aren't user-friendly"; others reply, "BSD *is* user-friendly; it's just picky about who its friends *are*."  Consider this section a lesson in making friends with your BSD system.

There are some excellent *built-in* sources of documentation on (almost) every BSD system.  The "System Manager's Manual" ("manpages") is powerful and legendary (and the origin of the saying "RTFM", which is defined below).  Example files, Developer whitepapers and 3rd part program documentation can be found on many systems.  And, because UNIX in general was (and still is) the backbone of the Internet, there are literally millions of pages of on-line information (assuming, of course, that you can find web pages that are both relevant and trustworthy/authoritative.

### RTFM! (Read the *friendly* manual) ###

From the earliest days of their existence, BSD systems have made extensive use of program documentation through "manpages", that is to say, the system's built-in manual pages.  While the interface may not be familiar to people who have no background in Unix-like systems, the "man" system is exceptional in the amount of and quality of documentation available, and ease of access.

A "manpage" exists for almost every program, device, library, system call, and configuration file on the system.  If you are aware of a program (let's say `kill`), simply typing `man kill` at the shell's prompt will present you the documentation for `kill(1)`, piped through your `$PAGER` (sometimes this is `more(1)`, but it is often `less(1)` --- don't get confused, because `less` is really `more`).

#### Advantages of `Man` pages ####

1. they include a brief synopis of the command syntax, flags, and options at the very top of the manual page; 
2. they are typically written by the developers themselves, so they tend to be more complete and accurate (than online "HOWTO's", for example); 
3. "manpages" are available on the system locally and from the basic terminal, and so they aren't subject to network interruptions or the current state of the GUI.

If you *are* running a GUI, then you can have your manpages put into a GUI window (try "xman").  Also, note that it is possible to install a BSD system *without* manual pages; if typing "man man" at your shell prompt produces an error (or no output), consult with someone about getting them installed.

For more details about manpage sections and usage, see [[Recognize_the_different_sections_of_the_manual]].

#### But I Don't Know What Manpage to Read! ####

In the event that you can only remember a portion of the file, try using `whatis(1)` or `apropos(1)`.  These programs search a database of installed documentation for the string you pass in as an argument.  `Whatis` returns fewer results (only exact matches), and `apropos` returns any manual page references that contain the string at all (so sometimes it's a good idea to pipe `apropos` to your `$PAGER`).

#### The Manual is Too Cryptic!!! ####

The manual intends to describe every program with enough detail to describe *all* of the behaviors and options available to the user.  It might be criticized because many manpages lack examples in sufficient quantity to apply to every conceivable situation (an arguably impossible task).  However, the manual pages are written to describe "everything to most people" instead of "exactly what *you* wanted to know today".  **R**eading **T**he **F**ine **M**anual usually has an answer, even if it is not as "easy" to glean as some other sources of information.

### Other BSD Documentation ###

#### The "Doc" Tree ####

Each Project has a team responsible for documentation of the system.  There is **lots** of data available if the documentation is installed.  A large number of small books and articles in many lanuages exist under /usr/share/doc on many systems.  Check your Project's website for information about Handbooks, FAQs and other resources produced by the Project's Documentation team.

#### Handbooks, Websites, Mailing Lists ####

Many of the "Doc Tree" resources are also available at your Project's web site.  Look for FAQs, handbooks and many of the other resources maintained by Project members to be available in a web format.

#### Example files ####

Example files live in a good many places on BSD systems, including "defaults" directories such as `/etc/defaults`, `/etc/rc.d/defaults`, `/boot/defaults`, and so on.  A good many example files and sample scripts for making life easier as a BSD sysadmin are located under `/usr/share/examples`.

#### Developer Whitepapers and Miscellaneous files ####

Many of these documents are very old (pre-dating modern BSD systems - e.g, dating back to the 1980s), but your "branch" of the tree may have newer papers as well.  Check the subdirectories of `/usr/share/doc` such as `papers`, `smm`, `psd`, and so on.

Other historical and occasionally useful docs live in /usr/share/misc, such as an ASCII table, the "BSD Family Tree" and more.

### 3rd party program docs ###

#### GNU Info pages and Perldoc ####

Many programs that are "contributed" software (for example, those from the Free Software Foundation) also have "Info Pages", which are displayed with (you guessed it) `info foo` (where "foo" is the program name).  If the software is FSF software, the `info` pages have a slightly different format; otherwise, `info` simply displays the manual page in a way similar to `man`.

#### Other sources of documentation ####

Occasionally software developers will "skimp" on manual pages for their software in favor of creating documentation in other formats.  If you find a manual page to be unsatisfying, try looking for text, HTML or PostScript/PDF documentation under `/usr/local/share` or `/usr/local/doc`, `/usr/local/share/doc`, etc.

Also, an Internet search can yield good results, particularly if it is very specifically worded, or, if a "general" search, you constrain the search to BSD-related websites, newsgroups, and mailing-lists.

### Examples ###


### Practice Exercises ###


### More information ###

apropos(1), man(1), man.conf(5), whatis(1), and info(1); share/doc/
and share/examples/; in addition, each BSD project maintains an online
handbook and several mailing lists