reST, mechamisms? (was Re: [Zope3-dev] Z3 documentation)

[Stephan Richter]

Hello Marcus,

On Thursday 03 April 2003 02:10, Marcus J. Ertl wrote:
> >I disagree. I have written successfully docs in Wikis which do not suffer
> > that shortcoming. In fact, if links are used wisely, they can have a
> > positive effect, since they lead you into deeper discussions.
>
> I'm no Zope develeper, so it may be wrong for me to take word in this
> place. But in my opinion Wikis are great for diskussions, but not for
> documentation.

I have never claimed that Wikis will be the final documentation form; but for 
now it is the best collaboration tool we have.

> What I need, for my daily(?) work with Zope3 is a more straight foward
> documentation:
>
> - Clear and complete API-References
> - Clear and straight forward Howto's
>
> At the moment, there is a real lag of such documentation. Many thinks
> in documentation tell me how something works, but not how to use it!
>
> :-(

Well, common and join the Z3 documentation team!!! Complaining does not create 
documentation, but actual contributions are needed. I have outlined many 
tasks to work on, which range in all sorts of difficulty levels.

I think we started to develop a fair amount of Howto's with the recipes of the 
Cookbook. Also, Paul's original Zopetop Primer was in Howto style. Now that I 
think about it, the Programmer's Tutorial and the "hello" package are also in 
Howto form.

We also did quiet some work on API references already. We have an interface 
introspector and a full ZCML reference. I think it is all just a matter of 
putting it together. 

But don't forget: We are still pre-beta...and for pre-beta we are doing pretty 
good in my opinion.

> And it would be usefull to know wich parts of documentation refer to
> realy working fuctionality, and witch is still Science Fiction.

I think this is often clearly marked. I do not think that any documents 
outside the Proposals section are Science Fiction; and if they are, they 
clearly marked. Status Batches do not exist without a  reason.

> In my opinion, you shouldn't stop someone, how wants to do
> documantation, but should help him as much as possible. There can't be
> such thing as "to much documantation".

When did I or anyone else do this? The only thing that I am blocking is the 
introduction of new tools for reasons I outlined before. It is from my very 
own experience with ZDP that formal tools do not help. If everyone coming to 
the Documentation Project introduces new tools, then we will never get 
anything usable. For now (until a beta release) the following methods are 
just fine for us:

- Wikis for most of the documentation; collaboration is far more important 
than versioning.
- CVS STX files for some API-related docs. 
- reST .hlp files for the OnlineHelp living in the source code.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training