Re: Newbie Guide (DRAFT)

[Stuart Henderson <stu@spacehopper.org>]

> Here are some basics in a nutshell with more details
> below:

Some useful information there. It would be good to point out 'man 
afterboot' explicitly in case anyone didn't notice it when they read 
'root.mail' as sent to root after a new installation... (apropos is also 
mentioned in root.mail, in the guise of 'man -k'). Though there's only so 
much you can do to direct people to the existing documentation...if they 
were going to read it, they most likely would have done so already.

I just noticed that the 'kernel configuration' section of afterboot(8) 
could benefit from a little discouragement - the edits (in-line, below) 
might be a starting point, but almost certainly needs refining...

... quick question to committers about man page style:

Am I correct in thinking it's preferred that the man pages as a whole 
should be fairly self-contained and not refer to other documents (FAQ, 
etc)? - Does an equivalent of style(9) exist for the man system, or is it 
just a case of "follow the existing style"? There's a difficult balance 
between brevity and including sufficient information; any help in 
maintaining the outstanding signal:noise ratio would be useful when 
suggesting changes.

> This is not a HOW-TO!

This is not a HOW-TO Operating System :-)



--- afterboot.8.orig    Tue Mar  1 21:22:58 2005
+++ afterboot.8 Tue Mar  1 21:29:16 2005
@@ -791,6 +791,12 @@
 to check on running processes, network connections, and opened files,
 respectively.
 .Sh COMPILING A KERNEL
+The standard OpenBSD kernel configuration (GENERIC) is designed to be
+suitable for most people. Use of an alternative kernel configuration is
+generally not recommended - in particular, bug reports are unlikely to
+be investigated unless a problem can be duplicated using a GENERIC
+kernel configuration.
+.Pp
 First, review the system message buffer using the
 .Xr dmesg 8
 command to find out information on your system's devices as probed by the