From owner-freebsd-doc Fri Oct 4 22:15:20 2002 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 3634337B401; Fri, 4 Oct 2002 22:15:19 -0700 (PDT) Received: from sccrmhc01.attbi.com (sccrmhc01.attbi.com [204.127.202.61]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6B5C043E4A; Fri, 4 Oct 2002 22:15:18 -0700 (PDT) (envelope-from swear@attbi.com) Received: from localhost.localdomain ([12.242.158.67]) by sccrmhc01.attbi.com (InterMail vM.4.01.03.27 201-229-121-127-20010626) with ESMTP id <20021005051517.UFVH6431.sccrmhc01.attbi.com@localhost.localdomain>; Sat, 5 Oct 2002 05:15:17 +0000 Received: from localhost.localdomain (localhost [127.0.0.1]) by localhost.localdomain (8.12.5/8.12.5) with ESMTP id g955IFoS028237; Fri, 4 Oct 2002 22:18:15 -0700 (PDT) (envelope-from swear@attbi.com) Received: (from jojo@localhost) by localhost.localdomain (8.12.5/8.12.5/Submit) id g955I9ZA028234; Fri, 4 Oct 2002 22:18:09 -0700 (PDT) (envelope-from swear@attbi.com) X-Authentication-Warning: localhost.localdomain: jojo set sender to swear@attbi.com using -f To: "Greg 'groggy' Lehey" Cc: Tom Rhodes , FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> <20021005020608.GE83766@wantadilla.lemis.com> From: swear@attbi.com (Gary W. Swearingen) Date: 04 Oct 2002 22:18:09 -0700 In-Reply-To: <20021005020608.GE83766@wantadilla.lemis.com> Message-ID: <751y75a2ge.y75@localhost.localdomain> Lines: 22 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) 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 Greg 'groggy' Lehey writes: > I'm not heavily involved in the doc project, but I'm seeing too many > rule-based modifications. Yes, overuse of the second person can be > annoying, but it must bee seen in context. I'd rather see people > write documentation which is intelligible and useful rather than > documentation which merely adheres to certain rules. Nobody can argue with the last two sentences, but but I'd hate to see them and that "too many" line discourage Tom from going hammer-and-tongs at the docs. I'll bet he fixes a lot more than he harms and the docs would be better off having him applying a lot of rules with a few less-than-perfect results than spending his time trying to make unintelligible sections intelligible -- a time-consuming and error-prone process. (He should leave that for AFTER class^h^h^h^h^hrule-applying.) It's not clear whether Greg said "too many" because he thinks that too many rule-based modifications made the text worse or because he thinks people are spending too much time doing that instead of improving intelligibility. I think Tom has his priorities straight in this matter. Make a quick-tho-less-than-optimal pass first, and then, if there's time, work on some of the hard stuff. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message