Date: Wed, 13 Jun 2001 15:09:15 -0700 From: "Eric Ogren" <eogren@stanford.edu> To: "Chern Lee" <chern@meow.osd.bsdi.com>, <freebsd-doc@FreeBSD.ORG> Subject: RE: Style/Grammar/Writing Guidelines Message-ID: <MLELJDKBCMIACMHOENLGGEOLCEAA.eogren@stanford.edu> In-Reply-To: <Pine.BSF.4.31.0106131439170.43965-100000@meow.osd.bsdi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Speaking as someone who's contributed a decent amount of stuff to the Handbook (in fact, I'm pretty sure that the passage you quoted was revised by me about a year ago), I don't particularly see a problem with the tone. Admittedly, I'm biased, but I don't really think of the Handbook as a technical, formal document -- I think of it as more of a "Here's how you use FreeBSD." The majority of the chapters are targeted towards more non-technical users, and as such, I think the fact that a lot of the handbook has an informal tone is actually a good thing. I find "You may need to prepare some floppy disks" just a lot nicer to read than "The first step to installing FreeBSD is to create the kern and mfsroot floppy disks." Again, I'm biased, since I much prefer to write informally, but that's my 2 cents. Eric -----Original Message----- From: owner-freebsd-doc@FreeBSD.ORG [mailto:owner-freebsd-doc@FreeBSD.ORG]On Behalf Of Chern Lee Sent: Wednesday, June 13, 2001 2:53 PM To: freebsd-doc@FreeBSD.ORG Subject: Style/Grammar/Writing Guidelines Hi: I'm helping read over the handbook in order to prep it for its next edition of the printed version. I feel this applies to not only the printed version, but also the handbook as a whole, and any other documentation we have. In reading the first two chapters, I've noticed that a lot of it is very loosely written--especially the second. This occurs throughout the handbook. Does anyone know of a style/grammar/writing guideline document for the doc project? If not, I propose that we come up with one. An example: You may need to prepare some floppy disks. These disks will be used to boot your computer in to the FreeBSD install process. This step is not necessary if you are installing from CD-ROM, and your computer supports booting from the CD-ROM. If you do not meet these requirements then you will need to create some floppies to boot from. (Ch. 2.2.1) Would be a lot more formal if written: The first step to installing FreeBSD is to create the kern and mfsroot floppy disks. These disks will be used to boot the computer into the FreeBSD install process. This step is not necessary if installing from the CD-ROM drive, and the computer supports booting from the CD-ROM. If the computer does not meet these requirements, then it is necessary to create these floppies. Reference to the reader as "you" is informal. Changing this to "One" or "The user" sounds very fitting to me. "Your computer" can be simply stated as "The computer." (not too sure if this sounds too great). Simply changing the form of verbs and slightly rewriting a sentence can fix most instances of "You/Your" as shown above. Sometimes it can even be omitted. Many more writing informalities and signs of loose, casual writing are apparent through what I have read so far. This is by no means criticism to the existing writing. The handbook just needs a more professional feel to it. I'm new at technical writing and am trying to put my high school journlism experience into making the handbook quality, print-ready material. Suggestions, please? - Chern Lee chern.lee@windriver.com Wind River Systems, Inc. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message 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?MLELJDKBCMIACMHOENLGGEOLCEAA.eogren>