From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.xemacs.design,gmane.emacs.devel Subject: "Extreme Documentation" [was: INFO on add-ons] Date: Tue, 03 Sep 2002 13:16:28 +0900 Organization: The XEmacs Project Sender: xemacs-design-admin@xemacs.org Message-ID: <877ki3wvvn.fsf_-_@tleepslib.sk.tsukuba.ac.jp> 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> NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1031026606 3981 127.0.0.1 (3 Sep 2002 04:16:46 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Tue, 3 Sep 2002 04:16:46 +0000 (UTC) Cc: xemacs-design@xemacs.org Return-path: Original-Received: from gwyn.tux.org ([207.96.1.200]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 17m57M-000126-00 for ; Tue, 03 Sep 2002 06:16:44 +0200 Original-Received: from gwyn.tux.org (localhost.localdomain [127.0.0.1]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id AAA05744; Tue, 3 Sep 2002 00:18:01 -0400 Original-Received: (from turnbull@localhost) by gwyn.tux.org (8.9.3/8.9.1) id AAA04766 for xemacs-design-mailman@xemacs.org; Tue, 3 Sep 2002 00:17:34 -0400 Original-Received: (from mail@localhost) by gwyn.tux.org (8.9.3/8.9.1) id AAA04742 for turnbull@tux.org; Tue, 3 Sep 2002 00:17:34 -0400 Original-Received: from tleepslib.sk.tsukuba.ac.jp (tleepslib.sk.tsukuba.ac.jp [130.158.98.109]) by gwyn.tux.org (8.9.3/8.9.1) with ESMTP id AAA04707 for ; Tue, 3 Sep 2002 00:17:33 -0400 Original-Received: from localhost ([127.0.0.1] helo=tleepslib.sk.tsukuba.ac.jp ident=steve) by tleepslib.sk.tsukuba.ac.jp with esmtp (Exim 3.36 #1 (Debian)) id 17m57A-0004nw-00 for ; Tue, 03 Sep 2002 13:16:32 +0900 Original-To: emacs-devel@gnu.org In-Reply-To: <3D73F89D.2070106@cox.net> ("David A. Cobb"'s message of "Mon, 02 Sep 2002 19:47:41 -0400") Original-Lines: 55 User-Agent: Gnus/5.090007 (Oort Gnus v0.07) XEmacs/21.4 (Informed Management, i686-pc-linux) X-Delivery-Agent: TMDA/0.61 X-XEmacs-List: design Errors-To: xemacs-design-admin@xemacs.org X-BeenThere: xemacs-design@xemacs.org X-Mailman-Version: 2.0.1 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Discussion of design and features for XEmacs. List-Unsubscribe: , Xref: main.gmane.org gmane.emacs.xemacs.design:1338 gmane.emacs.devel:7364 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:7364 >>>>> "David" == David A Cobb writes: David> Stephen J. Turnbull wrote: >> Footnotes: [1] Note also that Debian goes to extreme lengths to >> insure cooperation of packages it distributes among themselves, David> Um, you aren't saying this is a bad thing, are you Stephen? No. Merely that Debian users are highly unlikely to pose the kinds of problems that I'm thinking about when I write "nightmare". This serves Debian's purposes well, but among Linux and *BSD distros, it _is_ extreme. David> However a volunteer project likely can't take _extreme_ measures. Debian can and does (the Emacs Policy), as does the GNU Project (the FSF assignment policy[1]). The question is do the benefits justify the discouragement of contributions? And that largely depends on the contributors' perception of need for the measures. The problem with more strict documentation requirements is not that programmers see no need for documentation, or even no need for user- level documentation. 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. It certainly could be done by users (a) with only limited amounts of time or (b) with only limited acquaintence with the implementation. And one of the most frustrating things for any maintainer is a post of the form "it took me two hours to figure out how to do X, but I finally did. No thanks to the crummy docs!" And no thanks to you, either, for not telling us what you learned.... Users have a lot of information that the maintainers do not know. Aggregating that would be very useful, but how? FAQs are traditional, of course, and Wikis a more modern route. But these tend to take on a life of their own, and not get integrated into the distributed manuals and other docs. 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. Footnotes: [1] "Extremism in the defense of freedom is no vice." By the test of comparison with other projects, it is nonetheless extreme. -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN My nostalgia for Icon makes me forget about any of the bad things. I don't have much nostalgia for Perl, so its faults I remember. Scott Gilbert c.l.py