Date: 04 Oct 2002 22:18:09 -0700 From: swear@attbi.com (Gary W. Swearingen) To: "Greg 'groggy' Lehey" <grog@FreeBSD.org> Cc: Tom Rhodes <trhodes@FreeBSD.org>, FreeBSD-doc@FreeBSD.org Subject: Re: Plea to the doc team Message-ID: <751y75a2ge.y75@localhost.localdomain> In-Reply-To: <20021005020608.GE83766@wantadilla.lemis.com> References: <20021004212757.2a7e3227.trhodes@FreeBSD.org> <20021005020608.GE83766@wantadilla.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Greg 'groggy' Lehey <grog@FreeBSD.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?751y75a2ge.y75>