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

On Wednesday, December 3, 2003, at 11:40  PM, Jacob Smullyan wrote:

> 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

The other reason I would like to maintain a "traditional" documentation 
is because it adds a level of professionalism on our end. It is a 
single, clear resource that people can go to. Every other piece of 
software I have seen has not deviated far from this (except Freevo, 
<http://www.freevo.org>, who uses its Wiki as its documentation source.)

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

I do hope to get out of the documentation sprint the things that I 
purposely avoided because of my lack of knowledge in that area. It 
those bits and pieces that slowed me down. There are other things that 
I have just not done yet (particularly one - writing about the new 
session tools: the changes forced me to dump the old docs I written and 
start new - I just have yet to actually "start new." I did start to 
write some stuff in that.)

If you look at the documentation though, you will see that there are 
big gaping holes that need filling. Either that or the parts where it 
mysteriously sounds like it is from the original manual. Most of those 
are the things that I am not sure about.

I'll check in the current docs I have.


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

This is an excellent point. Any particular commentary that is produced 
after a release can be noted and considered for a next documentation 
release (which would, I guess, fall in line with final releases.)

(I think one good final goal in the project is to do what Apache does - 
stick HTML documentation in the webroot, in a manual/ directory.)

> I'm a bit torn.  I'm not at the point where I embrace the idea that
> the wiki would *be* the manual.

Yes ... the wiki has a clearly different purpose than being the 
"authority."

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

That was sort of the original idea I had. I actually copied, verbatim, 
the message catalog tutorial from my write-up on the Wiki. (I don't 
feel like writing it again. ;-) The wiki is a good source for 
approaching certain issues in little chunks

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