Subject: Informal poll: Installation instructions
To: None <email@example.com>
From: Michael Wolfson <firstname.lastname@example.org>
Date: 03/24/2001 12:52:11
OK, it's pretty apparent that the current set of installation notes is
unacceptable. I'm willing to rewrite them for 1.5.1, but I'd like to get
an idea of what the users (i.e. y'all) think is the most useful.
I'd appreciate if the opinionated among you and the people that had
troubles installing take a quick read and let me know which you feel is the
The possible meta-formats are:
"The NetBSD Way" (the way it's currently written)
Do not duplicate any information, have everything in order, but put in
paragraphs that are specific to a particular Open Firmware version.
Upside, easy to maintain the doc, but potentially confusing since each
version of Open Firmware has instructions that are contradictory to other
versions of OF.
"The Compromise" (the way I think it ought to be written)
For sections that have a lot of Open Firmware version-specific information,
break those sections apart into OF 1.0.x + 2.0.x, OF 1.1.x, OF 2.4, and OF
3 versions. In particular, the "How to enter Open Firmware" and the "How
to tell Open Firmware to load the bootloader" sections. For sections that
don't have much OF version-specific info, leave it combined, such as the
"How to place the installer on acceptable media" and the "How to use the
"Separate But Equal"
Essentially have four separate sets of installation instructions for each
class of OF versions. The major downside of this is four separate copies,
which will need to be updated individually each time something is changed.
The upside is that there's no confusing (and contradictory) information
that doesn't pertain to installing on your model.
"Basic plus HOW-TO"
Have a general overview of the installation procedure and have links to
HOW-TO style webpages for each class of OF versions. Same downside as
before (four separate copies), plus it requires a web browser and an
internet connection. This shouldn't be much of a problem since the native
OS for these machines comes with a web browser and AFAIK most Mac users are
connected to the internet. The major upside is (again) no confusing info
not related to your model, the ability to include images (such as snapshots
of Drive Setup), and links to useful info (such as how to use nvramrc).
I only have a limited amount amount of time to dedicate to this, so I'm not
willing to do more than one of these meta-formats.
Thanks for your feedback,