Re: [Chicken-users] Centralized documentation

[minh thu]

2007/2/12, Peter Bex <address@hidden>:
> 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
Hi,
I'm really not aware of the situation but here's two things:

Documentation on a wiki is nice to read and for collaboration but if
it's sufficiently good to be added to the main doc (which ships with
the code/library), it could be ennoying to manage. It would be
practical for the maintainers to see some kind of diff between the
wiki edited doc and the main doc, although for the reader there's no
difference. (From another point of view, wiki pages have to belong to
the doc, not to the wiki. If we add a lib or remove it, its doc is
automatically added or removed)

The fact there's multiple sites must not be a concern for the
maintainer. Any sync has to be performed by the sites themselves, thus
needing one kind of doc system.

Hope it makes sense for the above questions...

Cheers,
thu