From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "David A. Cobb" Newsgroups: gmane.emacs.devel,gmane.emacs.xemacs.design Subject: Re: "Extreme Documentation" [was: INFO on add-ons] Date: Tue, 03 Sep 2002 11:49:26 -0400 Organization: CoxNet User Sender: emacs-devel-admin@gnu.org Message-ID: <3D74DA06.1080005@cox.net> References: <3D728E82.8000808@cox.net> <87ptvxxkoj.fsf@tleepslib.sk.tsukuba.ac.jp> <87fzwtxad9.fsf@tleepslib.sk.tsukuba.ac.jp> <87adn1x705.fsf@tleepslib.sk.tsukuba.ac.jp> <3D73F89D.2070106@cox.net> <877ki3wvvn.fsf_-_@tleepslib.sk.tsukuba.ac.jp> Reply-To: emacs-devel@gnu.org, xemacs-design@xemacs.org NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Trace: main.gmane.org 1031068169 5803 127.0.0.1 (3 Sep 2002 15:49:29 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Tue, 3 Sep 2002 15:49:29 +0000 (UTC) Cc: "Stephen J. Turnbull" Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 17mFvj-0001VS-00 for ; Tue, 03 Sep 2002 17:49:27 +0200 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 17mGUU-0002EZ-00 for ; Tue, 03 Sep 2002 18:25:22 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10) id 17mFxH-0001Vs-00; Tue, 03 Sep 2002 11:51:03 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10) id 17mFw3-0001Gl-00 for emacs-devel@gnu.org; Tue, 03 Sep 2002 11:49:47 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10) id 17mFw0-0001Fq-00 for emacs-devel@gnu.org; Tue, 03 Sep 2002 11:49:45 -0400 Original-Received: from lakemtao02.cox.net ([68.1.17.243]) by monty-python.gnu.org with esmtp (Exim 4.10) id 17mFvz-0001Fg-00 for emacs-devel@gnu.org; Tue, 03 Sep 2002 11:49:43 -0400 Original-Received: from cox.net ([68.14.72.20]) by lakemtao02.cox.net (InterMail vM.5.01.04.05 201-253-122-122-105-20011231) with ESMTP id <20020903154943.XOVP12192.lakemtao02.cox.net@cox.net>; Tue, 3 Sep 2002 11:49:43 -0400 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.1b) Gecko/20020829 X-Accept-Language: en-us, en Original-To: emacs-devel@gnu.org, xemacs-design@xemacs.org Errors-To: emacs-devel-admin@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.0.11 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.emacs.devel:7393 gmane.emacs.xemacs.design:1346 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7393 Stephen J. Turnbull wrote: >"David" == David A Cobb writes: > > >The problem is that most of it is already >available in docstrings, so that creation of reasonably complete >functional documentation _could_ (at least in theory) be automated. > Yeah, I thought of that. Needs to bubble around a bit in my head before speaking. >It certainly could be done by users (a) with only limited amounts of >time or (b) with only limited acquaintence with the implementation. > F'rinstance: I have huge quantities of time available and I'm a better than average wordsmith. Getting organized is a problem, and misleading documentation is worse than none at all. >These alternative means of generating documentation undermine the >perception of need for documentation by the programmers themselves. >So it's hard to generate a consensus for a draconian docs policy. Nor >does "encouragement" work well; programmers, with much justification, >feel that their code contributions deserve weight and that they are >already contributing sufficiently to documentation. > Now that's just sad. -- David A. Cobb, Software Engineer, Public Access Advocate "By God's Grace I am a Christian man, by my actions a great sinner." -- The Way of a Pilgrim; R. M. French, tr. Life is too short to tolerate crappy software. .