This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Guile documentation [was Re: I resign as Guile maintainer]


Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

> On 1 Dec 1999, Greg J. Badros wrote:
> 
> > I'll also briefly take this opportunity to state what I claim is the
> > most significant problem with Guile:
> > 
> > Lack of reasonable documentation.
> > 
> > If I had to choose among extension languages right now, I'd be stunned
> > if Guile were my choice.  Only after the documentation improves will
> > people come to Guile to build a larger support infrastructure.  It's
> > just too damn hard to get started with Guile the way things are now.
> 
> Another important point with guile -- in my opinion -- is, that everything
> must be perfect before adopting it.  Most of the time this is a good
> attitude, but there are some points where something that at least works
> somehow would be better than nothing.  Documentation IMHO is one of these
> points, since even a maybe-not-perfect documentation system encourages to
> write documentation.  Compared to the effort of writing up documentation,
> the changes that may at some time be necessary if the documentation system
> will be improved/changed/completely restructured are of less importance.
> If we sum up the time wasted due to missing documentation _and_ the time
> lost for guile due to people that decided for a different language because
> of the lack of documentation, in the same time we could probably have done
> a couple of restructurings of a documentation system that was 
> maybe-not-perfect in the very beginning.

Agreed.

> Greg, you have quite a lot of experience with documentation issues.  The
> SCWM documentation system is very good.  Wouldn't it be comparably easy to
> adopt the SCWM system to guile?  You will know whether there are a few
> modifications that might make sense since there are probably a couple of
> lessons learned while using it.

Yes, cake.  I'm definitely willing to do this.  I've got one change that 
Jim and I discussed that I'll try out in Scwm before doing the docstring 
system in Guile.  As Richard Stallman has been quick to point out to me
in the past:  the docstring system is *not* sufficient by itself as
documentation -- it simply adds a great deal of value to the reference
material for the package.  But as I'm quick to respond, without the
reference manual, it's hard as hell for anyone else to write the
conceptual and tutorial material that is also desperately needed.

I'll want to coordinate with others who have code that needs checking in 
before the reasonably large (from the perspective of stupid text-based
software-engineering tools such as CVS) changes that applying the Scwm
docstring system to Guile will entail.  Details are forthcoming.

Greg

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]