Date: Sat, 2 Feb 2002 05:48:11 -0500 From: Michael Lucas <mwlucas@blackhelicopters.org> To: "Gary W. Swearingen" <swear@blarg.net> Cc: Andrew McKay <andy@openirc.co.uk>, freebsd-doc@FreeBSD.ORG Subject: Re: docs/34524: [PATCH] - Add important pre-installation notice Message-ID: <20020202054810.A26652@blackhelicopters.org> In-Reply-To: <0k3d0kk4ip.d0k@localhost.localdomain>; from swear@blarg.net on Fri, Feb 01, 2002 at 06:21:18PM -0800 References: <20020202005718.J61686-100000@fluoxetine.lan> <0k3d0kk4ip.d0k@localhost.localdomain>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <andy@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 majordomo@FreeBSD.org > with "unsubscribe freebsd-doc" in the body of the message -- Michael Lucas mwlucas@FreeBSD.org, mwlucas@BlackHelicopters.org my FreeBSD column: http://www.oreillynet.com/pub/q/Big_Scary_Daemons http://www.blackhelicopters.org/~mwlucas/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020202054810.A26652>