From owner-freebsd-doc Wed Jun 13 23:32: 4 2001 Delivered-To: freebsd-doc@freebsd.org Received: from mail.bfm.org (mail.bfm.org [216.127.218.26]) by hub.freebsd.org (Postfix) with ESMTP id 24FDF37B405 for ; Wed, 13 Jun 2001 23:31:51 -0700 (PDT) (envelope-from adam@whizkidtech.net) Received: from WhizKid (rh12.bfm.org [216.127.220.205]) by mail.bfm.org (Post.Office MTA v3.5.3 release 223 ID# 0-52399U2500L250S0V35) with SMTP id org; Thu, 14 Jun 2001 01:35:36 -0500 Message-Id: <3.0.6.32.20010614013121.00eb5100@mail85.pair.com> X-Sender: whizkid@mail85.pair.com X-Mailer: QUALCOMM Windows Eudora Light Version 3.0.6 (32) Date: Thu, 14 Jun 2001 01:31:21 -0500 To: Chern Lee , From: "G. Adam Stanislav" Subject: Re: Style/Grammar/Writing Guidelines In-Reply-To: Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org At 14:53 13-06-2001 -0700, Chern Lee wrote: >Reference to the reader as "you" is informal. Changing this to "One" or >"The user" sounds very fitting to me. Ouch! No, please no! >Suggestions, please? Forget what you learned in high school and take a Writer's Digest course! :) Seriously, much of the technical literature is so formal because it is written by people with no formal training in being a good writer. I once read a fantastic article on non-fiction writing in Writer's Digest which took some section from the New Testament, and rewrote it using the style of so many technical writers. Hahaha, did it ever kill the message! A handbook is of no use if it puts you to sleep in the first paragraph. Grab their attention, make them feel you are a personal friend who is trying to help them, and, by golly, make sure they understand what you are trying to teach them. The best technical writing reads like a novel! Cheers, Adam --- http://phonecowboy.com/registrar/twist/ finds a good domain for you and checks for its existence. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message