Re: [Chicken-users] Comprehensive documentation rewrite

[Elf]

On Wed, 13 Feb 2008, Shawn Rutledge wrote:
<snip>
> > That's why there shouldn't be "all these" doc overhauls, there should
> > be just one, resulting in proper documentation.
>
> It's better to work smart, not hard.  That means start by building the
> tools, to minimize the tedium.  A good example (outside the software
> domain) would be the human genome project...  But if you do it the
> hard way, then you will be even less inclined to ever do it again,
> even if the result was suboptimal and still needs improvement.
> Quality results from continuous improvement, not a one-pass "get it
> right and call it done".

not always true.  tex was better before the cycle of 'continuous improvements',
for something in this problem domain.  i dont know where the idea that 
anyone was proposing a be-all-and-end-all of documentation systems came from,
but its getting aggravating.  i proposed the following concepts:
a) felix is retiring/has retired.  we need something to lessen the learning
   curve for people being able to contribute.
b) the eggs and core use multiple incompatible documentation systems, making
   it difficult to have any semblance of consistency in terms of look-and-feel
   and in terms of quality.  additionally, the range of functionalities between
   systems is very large, making it trivial to do some things and impossible
   to do others.  this does not lead to maintainable or readable docs.
c) the only help available in the interpreter is so far out of date as to
   be useless.  this is a major inhibiting factor in terms of new growth
   and usability. 
d) there are many concerns (in the sense of interested parties) who want
   documentation available in different ways and with different formats,
   often with different properties and goals.
e) the systems currently in place have major drawbacks, including ease of use,
   ease of maintenance, and simplicity.
e) it is feasible to find a solution to these problems.  moreover, it is not
   difficult to solve 98% of it at once.  (this is in reference only to
   documentation, not felix stepping down.)

all that is required is a sufficiently flexible set of primitives that 
constrain their inputs.  no-one is trying for a perfect system, nor even
necessarily for something highly general.  this is a specific project for
a specific implementation of a specific language.  the goal atm is not even
something for all scheme (whatever that means these days).  the goal is 
for a workable system with no learning curve that people can and will use
easily that can generate the documentation desired with consistent presentation
and semantics.

this is a problem that has been occupying me for several months at this point.
i was hoping to have a concrete semiformal proposal by tonight.  ive been a
bit sidetracked with other things, so it probably wont be complete until 
tomorrow.  the proposal is intended as an rfc with a little code to back it
up, so that when some form of agreement is reached, there wont be a delay
before it can be used.

-elf