From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Max Techter Newsgroups: gmane.lisp.guile.devel Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 27 May 2003 04:02:21 +0200 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <868ystxi36.fsf@520000401788.dialin.t-online.de> References: <86wuh12yuc.fsf@520000401788.dialin.t-online.de> <3EB9828B00021495@pop1.tiscalinet.es> <86znlxdtwp.fsf@520000401788.dialin.t-online.de> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1054000659 12151 80.91.224.249 (27 May 2003 01:57:39 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Tue, 27 May 2003 01:57:39 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Tue May 27 03:57:37 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19KTib-00039p-00 for ; Tue, 27 May 2003 03:57:37 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.20) id 19KTjj-0005rD-AG for guile-devel@m.gmane.org; Mon, 26 May 2003 21:58:47 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.20) id 19KTjN-0005gZ-B6 for guile-devel@gnu.org; Mon, 26 May 2003 21:58:25 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.20) id 19KTjJ-0005VU-LA for guile-devel@gnu.org; Mon, 26 May 2003 21:58:23 -0400 Original-Received: from mail.gmx.net ([213.165.65.60]) by monty-python.gnu.org with smtp (Exim 4.20) id 19KTjI-0005KW-Sf for guile-devel@gnu.org; Mon, 26 May 2003 21:58:21 -0400 Original-Received: (qmail 22401 invoked by uid 65534); 27 May 2003 01:58:17 -0000 Original-Received: from pD9E77DAD.dip.t-dialin.net (EHLO 520000401788.dialin.t-online.de) (217.231.125.173) by mail.gmx.net (mp010) with SMTP; 27 May 2003 03:58:17 +0200 Original-Received: from max by 520000401788.dialin.t-online.de with local (Exim 3.35 #1 (Debian)) id 19KTnB-0003dy-00; Tue, 27 May 2003 04:02:21 +0200 Original-To: ricardmm@tiscali.es, Neil Jerram In-Reply-To: <86znlxdtwp.fsf@520000401788.dialin.t-online.de> Original-Lines: 153 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2445 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2445 Max Techter writes: > Ricard Mira writes: > > > Max Techter wrote: > > > What about a tutorial, Ricard? > > > > There is already a Guile tutorial, but it's quite incomplete. snip [some arguments concerning tutorials snipped away] > We should not bother too much about the structure > already there, if it is clear that there has to be > done some restructuring. > > There are well known > principles how to document a system. > ( And a standalone- (python), > or integrated-tutorial (bison) is a good ingredient for > the doc of every non trivial system) ;-) > > The problem is not so much in finding a suitable > structure but in writing and maintaining, without > washing the structure away again. > Keeping the proportions is a problem too, but > we do not have to bother about this, now. > > ( > The work already done, is a fine prototype. > We may infer the structure needed, from the > problems this documentation posed. > ). > > > Maybe I underestimate the complexity, of the needed > guile documentation. > > I`ll try to work out a proposal. > I am engaged in scheme and guile anyway, > and this will force me to have a structured go. > > (Guess I`ll need =< a fortnight) > I have to correct myself here. It should have been (Guess I`ll need >= a fortnight) Anyway, the work I promised to do is underway. Although I will not propose a ready made lay out. I`ll propose s.th. that is more like a process for getting a documentation design. What I did is s.th. like a documentation domain analysis. This takes shape right now. That is: A Domain Dictionary has been initialized. We need this for discussion. And then `The Guile Documentation Domain Dictionary' may serve for feeding the Glossary in the end. Use Cases are localized (They answer the question who, in which state, will consult which part of the documentation to find what) Some thought on dichotomies was spent: policy-mechanism concept-example etc. Important Documentation Patterns have been collected introduction-main-conclusion concept-example subtypes are: leading-example subsequent-example interleaved-example tutorial how to read this manual site-map elaboration abstract bold vision history etc As soon as GNU documentation guide lines are reached I`ll go public. I cannot go beyond this point without your sayings! Hopefully this procedure will naturally evolve into a process which extends to part of the guile community and specializes to Guile Documentation. My understanding of documentation development has been extended by doing these preparations. So the work done so far was at least valuable for me. Soon I call again, about those documentation issue ... (The promised `commented manual' is underway too). regards max. PS: * Some people say I tend to over analyze, but I doubt the thoroughness of their analysis ;-) * The whole `Guile (based on Scheme) concept' leaves me standing openmouthed, and I am wondering a) how it could happen that nobody pushed me into lisp/scheme before. b) why the project has not been mentioned in work dear to me eg. `Generative Programming' by Czarnecki and Eisenecker or Coplien`s `Multi-Paradigm Design', Thesis ( Maybe I overestimate the guile potential, but I constantly get this "whoop, you can do this and then you could do that" rush when working on scheme or guile. Time will tell... ) c) how it can be that some people, Stallman and others, are thus farsighted (includes the elisp choice). d) ... _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel