Re: [Chicken-users] egg documentation

[Alejandro Forero Cuervo]

> Ivan raised a good point on the Hackathon1 page (where he asks that
> people don't move his egg documentation out of the egg and into the
> wiki, because it's a pain to deal with eggs that don't have a copy of
> their docs in the egg directory itself).

I'm not sure I understand the problem here, so I'll share *my* vision
of how documentation for eggs should be handled in the ideal world.

Documentation for egg foobar should live in the chicken-eggs
repository, in wiki/foobar, in wiki format with some extensions for
including semantics.  By this I mean wiki syntax using tags such as
<procedure> ... </procedure>, from where some semantics can be
extracted by other tools.  I oppose using XML or some similar format
(eg. s-expr based format) on the basis that this would make it harder
for our users to modify.  Raising the bar required for editing, even
if only  slightly, can greatly reduce the number of contributions.

Documentation for eggs should not leave in the eggs' directories.
Instead, eggs should use the doc-from-wiki tag in their meta, so when
the egg gets created the latest version of the documentation gets
pulled from the wiki.

Documentation in the wiki should be generated from previous eggdoc
files only once.  When that has happened and the documentation has
been imported to the wiki, that should be considered the live version.
Regenerating the stuff in the wiki from eggdocs in the future clashes
against the spirit of encouraging users to help developers improve the
documentation.

Documentation should only live in one place: the wiki (with some
additional semantics).  HTML pages will be included with eggs if this
happens, eggs authors can modify their documentation with their
favorite editors and users can contribute and help improve it.

The only piece I see missing right now is that documentation can't be
posted to the wiki in a semanticly rich way from which other tools can
easily extract meaning.  I will probably work on that.

Can you explain to me why it is a pain for some to deal with eggs that
don't have a copy of their docs in the egg directory itself?

Alejo.
http://azul.freaks-unidos.net/