Re: generating a manual from annotations in source code

["Perry E. Metzger" <perry@piermont.com>]

As I say in another message, the issue is the distinction between the
"programmer's guide", "tutorial" or whatever you want to call it, and
the "reference manual". The difficulty in structuring the document you 
seem to have hit is precisely this difficulty.

You need a breezy, reasonbly high level document that takes a user
through the steps of doing various tasks, and then you need an
exhaustive reference manual that contains every function in every
module.

.pm

Mark Galassi writes:
> 
> I fully agree with Jim on all his points about generating docs from
> source.
> 
> I think that the real problem with Guile docs actually had to do with
> defining the product and its major categories more clearly.
> 
> Jim and Tim and I and others had made several good starts at
> reorganizing the manual, but after a while we never felt that the
> manual's structure was quite right, and after a while we would have
> trouble getting motivated to do any detail work.
> 
> I sometimes think the best thing might be to just write a long list of 
> chapters on rather fine-grained topics, and end up with a manual that
> has 30 or more chapters but no hierarchy beyond that.  That would be a 
> good start, and the organization could improve later when people
> figure out how to break it up into more coarse-grained categories.