Skunkweb documentation (was Re: skunkweb bug tracker)

Good evening all (or whatever part of the day it is from your
perspective),

Different topic, but you just kicked my brain into gear ...

Jacob said he would make this release of sw 'the documentation release'
(although he phrased it differently). Now, I'm willing to contribute,
but to me the whole documentation process is a bit misty (as to who does
what, what needs doing etc). May be it's just perception, but it's
pretty much a given that documenting things is the thing developers like
us don't like - therefor it should be as easy as possible to avoid a
constant struggle.

Therefor I've the following proposal (perhaps I cover some ground
already covered, in that case hit me with the clue-stick):

* Ditch the 'traditional' form of documentation currently used

* API documentation in docstrings -> use a generator to create useable
documentation (e.g. pydoc or perhaps happydoc, which has a few more
options)

* The more prose-like "glue" documentation like tutorials etc. in the
wiki -> we could take 'snapshots' of the wiki and distribute those as
static html with Skunkweb for the 'internet challenged'

Benefits imo:
* API documenation grows together with the code, one bit at a time, no
catching up to do (check if documentation is updated *before* allowing
to check into CVS)
* The barrier to contribute to other kinds of documentation becomes very
low and you get a bit more dynamics

For the api documentation we could start with everyone taking 1 or 2
major modules, as for the wiki I think we have enough raw material that
with a bit of restructuring we can make something beautifull out of it.

Comments, pebbles *), rotten tomatoes anyone ... :)

Rgds,
Jeroen

*) yet unknown people 'donated' 10 cubic meters of pebbles to the
principle of a school here in Holland - right on his front-porch, meant
as some sort of a threat (seems to be related to the fact that he'd
fired a handy-man who turned out to be a bit too handy with little
girls). Well, whoever did it has at least a certain sense of humor :)
 
On Tue, 2003-12-02 at 21:34, Brian Olsen - Lists wrote:
> Just a note that it would be much help if we shoved all our bug reports 
> into the sourceforge bug tracker. at least for myself, I will be 
> looking at it more frequently now. i got a few to add (which I am going 
> to work on myself anyway) but at least some of these wily bugs will be 
> reported in a single place. Also, it makes it look like skunkweb is not 
> floating dead in the water. More open/closed bugs + feature requests 
> makes the project look alive and kicking!
> 
> Brian
> 
> 
> 
> -------------------------------------------------------
> This SF.net email is sponsored by OSDN's Audience Survey.
> Help shape OSDN's sites and tell us what you think. Take this
> five minute survey and you could win a $250 Gift Certificate.
> http://www.wrgsurveys.com/2003/osdntech03.php?site=8
> _______________________________________________
> Skunkweb-list mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/skunkweb-list


-------------------------------------------------------
This SF.net email is sponsored by OSDN's Audience Survey.
Help shape OSDN's sites and tell us what you think. Take this
five minute survey and you could win a $250 Gift Certificate.
http://www.wrgsurveys.com/2003/osdntech03.php?site=8