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

On Wednesday, December 3, 2003, at 03:47  PM, Jeroen van Dongen wrote:

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

The documentation process is a bit slow. I still need to check in a 
bunch of stuff that I made corrections to.

Jacob and I are conveniently located in the same geographic area (New 
York), so this gives a chance to meet about the documentation (which 
might happen this week.) The plan is to write as much documentation as 
possible to the point, at the least, to a first complete draft of the 
documentation.

But I do agree with you - we have made the whole process a bit misty. I 
think along with the version 3.4 release, we can also ramp up to a 
little more open-ended organization. This is why I started off by 
suggesting that the bug tracker should be used more, because it opens 
up the development process more.

To be clear of what is happening now:

1. My goal is to finish the API documentation at our little 
documentation sprint. I did a major change in my working copy of the 
documentation where each API is in separate chapters ... a chapter on 
AE, a chapter on HTTP/Sessions, etc.

2. Since there are finer points in the Installation and Configuration 
chapter(s) that I am not particularly sure of, I would like to delegate 
that to someone else.

(I am practically always on the #skunkweb IRC channel ... lately I have 
been the only one there. :-) If you do get a chance, please step in so 
we can discuss any fine points that need to be addressed. Hopefully 
Jacob and I will find a place with network access when we do our little 
documentation sprint, so I think it would be great if you (or anybody 
else for that matter) stop in, if you have time, and be a part of this 
sprint. This would be of incredible help, I feel.)

3. The sw.conf Parameters chapter is a bit aged, meaning that it is 
exclusionary of newer parameters that were added.

4. Besides that, there are lot of [TODO]s littered across the 
documentation that still need to be clarified and/or worked on.

5. A general organization of the manual is this:

Preface
Section I: Installation
	Installation/Configuration
Section ||: API
	HTTP
	AE
	Database Access
Section III: SkunkWeb Services
Section |V: STML
	STML Reference
	Extending STML
Section V: Extending SkunkWeb
	A Preview Of The SkunkWeb Internals
	Writing SkunkWeb Services

Is it particularly in this order yet? Nope.

Some finer points in this:

a. I started converting the LaTeX source of STML to ReST. Once that is 
finished, I am going to clean up anything that needs to be cleaned up 
there and then call that the STML Reference.
b. Extending STML, A Preview ... and Writing SkunkWeb Services are not 
things I started on yet.
c. There is no "Fundamentals" Section in here. My goal is to make one 
manual as purely reference. I am thinking that a separate fundamentals 
manual can elaborate further than the intent of what the reference 
manual is.

This is the general situation now with the documentation.

> 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

Actually, I think we should have as much documentation as possible, in 
many different ways. People learn differently, and might benefit from 
one over the other. Also, I think it would be good to have hanging 
around anyway.

(Actually, I am being conservative on this issue. I wrote too much 
already.)

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

This would be useful.

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

I think that the API documentation will have a distinctly different 
flavor than the traditional documentation. I think therefore, that both 
should co-exist with each other.

You got a point though - it is easier to update the API documentation 
within the code than having to run to a different source. Developers 
will add the documentation in their code.

So, I propose this - one or more persons handle the traditional 
documentation. Those adding new features notify the documentation group 
of this addition. The documentation group then logs this new feature in 
to their documentation TODO file, and when a final release is made, all 
the new features will be explained in the new official documentation 
for that new release.

> * The barrier to contribute to other kinds of documentation becomes 
> very
> low and you get a bit more dynamics

I think, from what I suggested, the dynamic between on-the-spot 
documentation and official documentation will be good.

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

My plan is to also attack the Wiki's disorganization. When that comes 
around, I will also put up a page on the wiki suggesting how to follow 
the organization when adding new documentation to it.


Since I will be getting a chance to talk to Jacob, we will be able to 
discuss how we can go forth with more organization. The bug tracker is 
one step in that direction since it will help us see the progress on 
bugs and such.

I hope this clears up certain issues you have been having - I'd like to 
see things cleared up more as well.

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