Re: Doc organization (Re: Around again, and docs lead role)

[Max Techter <mtechter@gmx.de>]

Max Techter <mtechter@gmx.de> writes:

> Ricard Mira <ricardmm@tiscali.es> 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