Re: Skunkweb documentation (was Re: skunkweb bug tracker)

On Wed, Dec 03, 2003 at 09:47:07PM +0100, Jeroen van Dongen wrote:

> 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.

Agreed!

> 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

I think it is a bit early to ditch it.  The manual is still in very
early stages and I haven't yet made a serious effort to work on it.
Brian did a chunk of work early on and it has sort of languished.  As
he mentioned in his post, we are going to get together, most likely
next week it now seems, to have a doc sprint.  What I'd like to emerge
from that is enough structure so that it would easy for others to
contribute -- and perhaps irc-based doc sprints as Brian suggested
would make collaboration easier and generally be motivating. 

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

Improving this documentation is a very good idea.  I typically first
look at pydoc documentation for modules and very much appreciate it
when it contains something good to read, including example code.

> * 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'

I don't mind using the wiki for documentation, but I think that a
handbook needs an authoring process a little different from anything
that would appear organically on a wiki.  So perhaps we can put the
results of the first sprint up on the wiki as well as in cvs, let
people add comments and suggestions -- I'm reminded of postgresql's
interactive documentation -- and then merge them back into cvs.
Merging them back and forth would be a bit tedious, so we'll need to
figure out some approach for this.  It would be useful to separate the
text of the manual itself from commentary about it with some sort of
markup, by convention, to make the merge process smoother and require
less editorial busy-work.

I'm a bit torn.  I'm not at the point where I embrace the idea that
the wiki would *be* the manual.  But the main thing is to extract the
maximum amount of documentation from hapless community members before
they realize they've been had.  If a wiki is an easier way for people
to contribute to something that furthermore stands a chance of turning
into into good traditional documentation, then I'm all for it.

> 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.
 
What modules do you want to take?  They're yours. :)

Pebbles in mouth,

js

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQE/zrqguqamFyFXXLIRAlakAJ9YEgYoCmOhxTfjvha9biUE5eQc0QCdFvtA
BbUbKu7pVJJvWUSKoUqqeYE=
=TAS4
-----END PGP SIGNATURE-----