[Chicken-users] Centralized documentation

[Peter Bex]

Hi everybody,

I was having an e-mail discussion with Mario Domenech Goulart about Spiffy
and the conversation turned towards egg documentation.
The discussion started because Spiffy's documentation is starting to
grow beyond what fits comfortably on one webpage (which is the case at this
moment).  We both agreed the best place would probably be on the wiki,
perhaps like lighttpd does it (http://www.lighttpd.net)

Here's the relevant part of the discussion:

----- Forwarded message from Mario Domenech Goulart <address@hidden> -----
> > > How would [keeping a synched copy of the documentation from the wiki
> > > on call/cc.org] work if we use more than one page?
> > 
> > Hmmm. I don't know.  I'd expect we'd have an index page (which would
> > be copied to call/cc.org's eggs directory) and the links would point
> > to galinha.  But I don't know if it is the right way.
> 
> What's the point of duplicating the index then?  We could just point to
> galinha and be done with it.

That would be the more atraightforward alternative.

> Saves us the trouble of updating the call/cc page every time.  Maybe
> Felix should think about ditching the egg pages altogether and
> simply linking to Galinha as the one and only resource for egg
> documentation.  It would remove a lot of overhead and duplication,
> IMHO.  I never liked having two systems which do the same thing
> (which is one reason why I despise GNU's policy wrt info pages over
> manpages).  It confuses me.  Where do you look for the most recent
> info?  Who sees what system as authoritative?  Do people think to
> update the other version at all?  Do some people switch their
> standpoint sometime later, changing which system I need to look at?
>
> This is definitely not good for newbies.  They might be scared away in
> confusion.  You might think this is silly, but if I think it, I'm sure
> there are others.

I see your point.  My guess is that Felix wants to keep the official
documentation at call/cc.org.  But it's just a guess.  We have to ask
him.


> > Do you think the Spiffy documentation and this documents containing
> > tips should be the same?
> 
> It could be a section in the documentation.  Since it's a wiki, the nature
> of documentation is a lot more volatile.  I'm not sure what's best yet.

Ok.  So let's try to solve the case of the canonical Spiffy
documentation in a way we can accomodate further documents in the
future.
----- End forwarded message -----

What do you think would be the best way to go from here?  I really believe
one canonical place for documentation is a benefit both for experienced
developers as well as for newbies and the documentation maintainers.
Having two or more places where documentation can be found or generated
(wiki syntax, eggdoc format and plain HTML) causes a lot of confusion
and duplication of work.

The current situation conveys chaos and disagreement to outsiders, I think.
If we want to attract more developers to get more work done (we all agree
on that being a good thing), a sane documentation system would go a
long way towards at least giving the appearance of a well-engineered
and structured project.  (Having a ticket tracking system helps similarly
and I wish to thank Felix and Arto for setting it up.  I agree with Felix
that everybody should register a login there)

Should eggdoc be deprecated in favor of svnwiki?  Should the wiki be
deprecated instead?  Should we stick with the status quo? (IMHO, no,
but I can imagine some people might feel the same about this as about
version control systems)

Any other ideas would be welcome.

Regards,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgpxmofclCBZr.pgp
Description: PGP signature