Date: Wed, 13 Jun 2001 14:53:08 -0700 (PDT) From: Chern Lee <chern@meow.osd.bsdi.com> To: <freebsd-doc@freebsd.org> Subject: Style/Grammar/Writing Guidelines Message-ID: <Pine.BSF.4.31.0106131439170.43965-100000@meow.osd.bsdi.com>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.31.0106131439170.43965-100000>