[Zope3-dev] RE: Z3 documentation (again)

[Garrett Smith]

I suspect we'll probably see comments like this until a final set of
docs land for Z3. Personally, I like this sort of feedback as its
helpful to know what people are look for.

> > What I need, for my daily(?) work with Zope3 is a more=20
> 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.=20
> Many thinks
> > in documentation tell me how something works, but not how to use it!

I would say it's clear that the Z3 docs are not usable for newcomers. I
hope to help out here, where I can.

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

I don't read this as complaining :-)

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

I agree! But the burden on docs is going to be huge as more and more
developers want to start using, what will undoubtedly be considered, the
best app server ever built!

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

Uh...I gotta call this one out. In my experience, docs are as critical
as code -- they're the user interface to everything. This would be like
saying there can't be too many modules or APIs or languages to learn.

To be clear, I completely agree that anyone should be able to
contribute, and in a flexible, easy manner. But we perhaps should
distinguish between project artifacts and high quality end user docs.=20

> When did I or anyone else do this? The only thing that I am=20
> blocking is the=20
> introduction of new tools for reasons I outlined before. It=20
> is from my very=20
> own experience with ZDP that formal tools do not help. If=20
> everyone coming to=20
> the Documentation Project introduces new tools, then we will=20
> never get=20
> anything usable. For now (until a beta release) the following=20
> methods are=20
> just fine for us:
>=20
> - Wikis for most of the documentation; collaboration is far=20
> more important=20
> than versioning.
> - CVS STX files for some API-related docs.=20
> - reST .hlp files for the OnlineHelp living in the source code.

A couple questions:

- Why is a "beta" such an important trigger for starting a more robust
end user docs process? This is not a rhetorical question :-) ...is
nothing stable enough to document in its final form at this point?

- What problems do you see with running two efforts in parallel --
informal Wiki based documentation (perfect for flexibility and
collaboration) and, at least the early stages of, formal end user docs
in a format that makes sense for a Z3 GA release?

Garrett Smith
Mojave Corporation