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

[Stephan Richter]

On Thursday 03 April 2003 10:32, Garrett Smith wrote:
> > > 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.

Really? I think the Programmer's does a really good job as an introduction. I 
think you intended to say that there is not enough documentation for the Site 
Developer; however, Zope 3 does not aim at this group at this point and tools 
for Site development are just being developed as we speak.

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

No, we can do plenty of documentation. But before the beta, mainly core 
developers and very interested people are going to look at Zope 3, so it must 
be as easy as possible to make comments and add to the documentation for 
these people (since they know the code best). All of the core Zope 3 
developers know and are using Wikis, so it is natural to them. Furthermore, 
before the beta we do not have to worry about versioning of the docs.

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

I see a couple of problems:

1. The developers are much less likely to read over the documentation and 
therefore the technical quality will suffer. Even if they do, collaboration 
will be much harder, since they do not know how to comment directly.

2. Because of point (1) the "formal" documentation will lack behind.

3. With "formal" you probably mean using yet another tool. This will raise the 
entry bar for many. Remember, most people do not lurk into the Zope3-Dev 
mailing list because they want to write documentation, but develop with and 
for Zope 3.

4. A split in efforts will spread documentation even more while we should try 
to pull it more together. I mean seriously, currently only five people (I can 
come up with) have contributed significant amounts to the documentation, four 
of which are core developers. There is simply not enough manpower behind it 
to formalize it at this point... this is Open Source.

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