>Number:         37012
>Category:       install
>Synopsis:       The online instructions for setting up RAIDframe aren't as clear as would be good
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    install-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Sep 21 07:40:00 +0000 2007
>Originator:     Chris Ross
>Release:        4.0_RC1
>Organization:
>Environment:
N/A
>Description:
Re:  http://www.netbsd.org/docs/guide/en/chap-rf.html

The documentation for setting up RAIDframe "feels" out-of-date.  I'm told that little has changed with RAIDframe recently, but the document clearly has the feeling of a document that was written for NetBSD 1.x, and has been "updated" to 2.0 (and/or later).  It doesn't flow well for someone setting up RAIDframe on any recent release of NetBSD.

The above is a general statement.  The specific purpose of this P/R is to note the lack of clarity in the dc(1) magic that's prescribed for configuring the underlying disks to accept crash dumps (in section 15.3.7).

The first time I did this, I didn't understand where all of these numbers came from.  I would suggest:

1) Using bold-facing or some other presentation characteristic, at least in the non-text versions, to indicate which lines are inputs to dc, and which are output from dc.
2) Use italics, or some other indication, to note that the magical "1008" used in the sparc64 fomulae needs to be drawn from the specific disk you're dealing with in each case.  This *is* mentioned above, but little point is made of it, and when cutting-and-pasting from the dc(1) input, it is easy to lose that piece of information.

Much of this is presentation issue, but.
>How-To-Repeat:
Read the documentation in section 15.3.7, and try to configure a RAIDframe for booting (and accepting crash-dumps) on a sparc64.  If you don't already know the process well, you will likely be tripped up in a few places.
>Fix: