docs/34524: [PATCH] - Add important pre-installation notice
hi...@uk.freebsd.org
>Number: 34524
>Category: docs
>Synopsis: [PATCH] - Add important pre-installation notice
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Fri Feb 01 02:30:00 PST 2002
>Closed-Date:
>Last-Modified:
>Originator: Hiten Pandya
>Release: FreeBSD 5.0-CURRENT i386
>Organization:
The FreeBSD Project
>Environment:
System: FreeBSD hpdi.ath.cx 5.0-CURRENT FreeBSD 5.0-CURRENT #1: Wed Jan 30 02:25:36 GMT 2002 ro...@hpdi.ath.cx:/c1/obj/data/dev/src/sys/CURRENT5 i386
>Description:
The below patch will add an important <note> section which will
remind the users to update their firmwares before installing
FreeBSD, as this could be a problem.
Half the PRs in the Database, are lying their becuase the users
did not update their Firmware BIOS, and stuff..
Hope it gets in ;)
-- Hiten Pandya
-- <hi...@uk.FreeBSD.org>
>How-To-Repeat:
n/a
>Fix:
--- chapter.sgml Fri Feb 1 09:51:03 2002
+++ chapter.sgml.new Fri Feb 1 10:14:32 2002
@@ -4553,6 +4553,13 @@
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.</para>
+ <note>
+ <para>It is very important, that you apply the neccessary firmware
+ updates before starting the installation, or if you encounter a
+ problem booting-strapping the system. By ensuring this, you can
+ save yourself a lot of problems in the future.</para>
+ </note>
+
<sect2>
<title>What to Do If Something Goes Wrong...</title>
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majo...@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Andrew McKay
> + <note>
> + <para>It is very important, that you apply the neccessary firmware
> + updates before starting the installation, or if you encounter a
> + problem booting-strapping the system. By ensuring this, you can
> + save yourself a lot of problems in the future.</para>
> + </note>
The following patch removes the suggestion that everyone should upgrade
their BIOS before installation (oh, the horror!) and contains no spelling
mistakes or grammatical errors that I can see. Both of these do, I
believe, set it apart from the original patch and thus I present it for
review.
As usual, a copy is available as the top link at:
http://www.openirc.co.uk/freebsd/
--- chapter.sgml Thu Oct 25 09:27:51 2001
+++ chapter.sgml.new Sat Feb 2 00:50:00 2002
@@ -4432,6 +4432,20 @@
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.</para>
+ <note>
+ <para>Many installation problems can be avoided or alleviated by
+ updating the firmware on various hardware components, most notably
+ the motherboard. If the installation fails to work then updating
+ the BIOS may solve the problem. Refer to your motherboard
+ manufacturer's website for information on BIOS revisions and upgrade
+ instructions.</para>
+ <para>Most manufacturers strongly advise against upgrading motherboard
+ BIOSs unless you have a good reason for doing so. The
+ process <emphasis>CAN</emphasis> go wrong, causing the BIOS to be
+ destroyed permanently. Therefore <emphasis>DO NOT</emphasis> do
+ this unless you believe it will solve your problem.</para>
+ </note>
+
<sect2>
<title>What to Do If Something Goes Wrong...</title>
---end diff---
Comments/suggestions?
--
Andrew McKay <an...@openirc.co.uk>
Andrew McKay
Michael Lucas
This looks much better to me.
One minor nit: you combine an emphasis and CAPITALS. I'd just use
<emphasis>. Combining italics and capitals isn't very
professional-looking. It's like the use of multiple exclamation
points.
Gary, this isn't bikeshedding. This is (please ignore) bikeshedding:
Also, the patch contains a lot of passive voice; rewrite it in active
voice. Also, the fourth sentence and the fifth sentence should be
swapped. Plus, we need links to various manufacturers' warnings to
this effect, as reinforcement.
See the difference? :-)
On Fri, Feb 01, 2002 at 06:21:18PM -0800, Gary W. Swearingen wrote:
> Andrew McKay <an...@openirc.co.uk> writes:
>
> > + <note>
> > + <para>Many installation problems can be avoided or alleviated by
> > + updating the firmware on various hardware components, most notably
> > + the motherboard. If the installation fails to work then updating
> > + the BIOS may solve the problem. Refer to your motherboard
> > + manufacturer's website for information on BIOS revisions and upgrade
> > + instructions.</para>
> > + <para>Most manufacturers strongly advise against upgrading motherboard
> > + BIOSs unless you have a good reason for doing so. The
> > + process <emphasis>CAN</emphasis> go wrong, causing the BIOS to be
> > + destroyed permanently. Therefore <emphasis>DO NOT</emphasis> do
> > + this unless you believe it will solve your problem.</para>
> > + </note>
>
> Looks good to me. I tend to not like preachy docs, so I'd probably
> leave out that last bit of advice, but it's OK. And I'd change
> "fails to work" to "fails,", but that's OK as-is too. One more --
> I'd probably change "Many" to "Some" at the beginning. No need to
> waste time on it further if you'd rather not change it or disagree.
>
> (Is this what they call bikeshedding, or is it more-or-less welcome?)
>
> To Unsubscribe: send mail to majo...@FreeBSD.org
> with "unsubscribe freebsd-doc" in the body of the message
--
Michael Lucas mwl...@FreeBSD.org, mwl...@BlackHelicopters.org
my FreeBSD column: http://www.oreillynet.com/pub/q/Big_Scary_Daemons
http://www.blackhelicopters.org/~mwlucas/
Andrew McKay
> Looks good to me. I tend to not like preachy docs, so I'd probably
> leave out that last bit of advice, but it's OK.
See revised patch below. Did you mean lose the whole second paragraph?
I think pointing out the seriousness of this step is important so I've
left in the bit about the fact that the process CAN go wrong but removed
the bit telling people not to do it. I would hope that being told your
motherboard could be permanently destroyed pretty much implies 'do not do
this unless you have a compelling reason'. The whole paragraph could go
if it's a problem.
> And I'd change "fails to work" to "fails,", but that's OK as-is too.
> One more -- I'd probably change "Many" to "Some" at the beginning.
Agreed. 'fails to work' sounds worse on a re-read and 'Many' implies a
greater frequency than is actually true.
> (Is this what they call bikeshedding, or is it more-or-less welcome?)
Constructive criticism is something that I always find worthwhile. Thanks
:)
-<PATCH>- also at: http://www.openirc.co.uk/freebsd/install.diff
--- chapter.sgml Sat Feb 2 12:18:14 2002
+++ chapter.sgml.new Sat Feb 2 12:22:45 2002
@@ -4553,6 +4553,18 @@
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.</para>
+ <note>
+ <para>Some installation problems can be avoided or alleviated by
+ updating the firmware on various hardware components, most notably the
+ motherboard. If the installation fails then updating the BIOS may
+ solve the problem. Refer to your motherboard manufacturer's website
+ for information on BIOS revisions and upgrade instructions.</para>
+ <para>Most manufacturers strongly advise against upgrading motherboard
+ BIOSs unless you have a good reason for doing so. The
+ process <emphasis>CAN</emphasis> go wrong, causing the BIOS to be
+ permanently destroyed.</para>
+ </note>
+
<sect2>
<title>What to Do If Something Goes Wrong...</title>
-</PATCH>-
--
Andrew McKay <an...@openirc.co.uk>
Andrew McKay
From: Andrew McKay <an...@openirc.co.uk>
To: "Gary W. Swearingen" <sw...@blarg.net>
Cc: freeb...@FreeBSD.ORG, <freebsd-gn...@freebsd.org>
Subject: Re: docs/34524: [PATCH] - Add important pre-installation notice
Andrew McKay
From: Andrew McKay <an...@openirc.co.uk>
To: freeb...@freebsd.org
Cc: freebsd-gn...@freebsd.org
Subject: Re: docs/34524: [PATCH] - Add important pre-installation notice
Date: Sun, 3 Feb 2002 00:32:32 +0000 (GMT)
On Sat, 2 Feb 2002, Michael Lucas wrote:
> One minor nit: you combine an emphasis and CAPITALS. I'd just use
> <emphasis>. Combining italics and capitals isn't very
> professional-looking. It's like the use of multiple exclamation
> points.
This should, therefore, be the best patch ever...being as it is the
combined efforts of me, Gary and Michael. And yeah, I had reservations
about the combination of <emphasis> and CAPS but I went with it because
you can never have too much stress...or something :)
-<PATCH>- also at: http://www.openirc.co.uk/freebsd/install.diff
--- chapter.sgml Sat Feb 2 12:18:14 2002
+++ chapter.sgml.new Sat Feb 2 12:22:45 2002
@@ -4553,6 +4553,18 @@
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.</para>
+ <note>
+ <para>Some installation problems can be avoided or alleviated by
+ updating the firmware on various hardware components, most notably the
+ motherboard. If the installation fails then updating the BIOS may
+ solve the problem. Refer to your motherboard manufacturer's website
+ for information on BIOS revisions and upgrade instructions.</para>
+ <para>Most manufacturers strongly advise against upgrading motherboard
+ BIOSs unless you have a good reason for doing so. The
+ process <emphasis>can</emphasis> go wrong, causing the BIOS to be