[Zope3-dev] Z3 documentation

[Stephan Richter]

Hi Garrett,

as Sathya metioned, I try to keep the documentation group focused and 
oriented. The main page used for the organization of the tasks and available 
documentation is 
http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/Documentation

On Monday 31 March 2003 11:56, Garrett Smith wrote:
> I've got some time over the next few months to contribute to the Z3
> effort. Having looked over the technology, there's not much I can
> contribute to in the way of coding -- too new to Python and Z3.

Cool!

> However, I might be able to help in the area of documentation. I've
> managed development efforts involving some commercial ISVs and have a
> pretty good idea what's involved in delivering high quality docs,
> particularly for frameworks and tools.

Also cool. :-)

> Having read through the mailing list archives, I've made a few
> observations:
>
>  - Z3 appears to be congealing (typical for alpha stage) and that's
> usually a great time to get docs going.

I agree.

>  - The list is starting to see frequent requests for better docs from
> the new and curious. The temptation is strong to respond with "write 'em
> yourself, y' whiner" -- but it helps if they have a process/project to
> plug into.

Right; we try very hard to emphasize documentation from the beginning.

>  - There was talk of Z3 docs back here:
> http://mail.zope.org/pipermail/zope3-dev/2002-November/003357.html - but
> I haven't seen much activity on it

Well, there has been. A lot of the activity is logged in the Zope 3 CVS and on 
the Wiki mentioned above.

> My company has decided to use Z3 as the platform for some business
> applications we're developing, so we have a strong interest in seeing Z3
> succeed. My involvement, to whatever extent is needed, will make that
> more of a vested interest.

Nice.

> 1. Is now a good time for a more focused effort on "docs" for Z3? I
> realize the answer depends on a definition of what "docs" means --
> leaving this intentionally flexible. Thoughts?

Yes; on the Wiki page mentioned above, I tried to outline all the 
documentation-related tasks.

> 2. Is there a project handling this already that I've overlooked?

Yes, the Documentation sub-project that is organized via the Wiki.

> 3. Is this the right protocol for volunteering? Do I need to fill in an
> application somewhere -- talk to any recruiters? ;-)

Certainly. If you want to write docs that make it into CVS, you can either 
give it to anyone with checkin rights or sign up for CVS access. For the 
Wikis you just need a Zope.org username.

> Btw, I recognize that there's a lot of documentation for Z3 (have read
> it), most of which is quite good. It's rare to see such a disciplined
> approach for any project, much less an OSS project. But by "docs", I
> don't mean project artifacts or API documentation. I'm talking about
> end-user docs -- i.e. developer guides, references, (more) tutorials,
> etc. that can be easily accessed.

Right, I think at this point we should drive to get the Cookbook up-to-date 
and write new recipes for it. I think there we will spend our time most 
wisely and people can learn about specific problem domains quickly using the 
cookbook. Of course, you can sign up for any other task too and/or add new 
tasks.

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