[Zope] reality check

[Jason Cunliffe]

At 09:10 10/12/99 -0500, Christopher Petrilli wrote:

>We do have someone hired purely as a tech writer, but we also have to have
>the material to do the work with, and most of our people are working on
>other "paying" projects.  In the end the company does have to flow cash.
>The ZDP project has been doing an admirable effort at attempting to get more
>documentation written, but the job is not as easy as it looks at the outset.
>Writing good documentation is not easy.  Witness most products.
>
>While the documentation of Zope is not great, I'd take offense that it's the
>"worst" on the market.  You've obviously not experienced the problems of
>voluminous documentation that is simply wrong, for the wrong version, or
>unindexed.  10,000 pages without an index is less useful than 1000 with.

#1 Please_ don't misunderstand me. I am not bitching, and I personally do
not consider Zope "worst" in any sense. On the contrary it is IMHO one of
the "best" things happening at the moment.
It is partly because of he intense activity here that it is so hard to keep
up. I look way for few days to do =other work and hardly know how to begin
again. 

Voluminous documentation that is wrong -- arghh yes - look at computer book
publishing now. telephone books of in_from_ation but not well structured,
little context, overview, etc. It is rare to find concise works. And they
do take a long time and a lot of work to get there. Even 'normal'
illustrated books represent a huge amount of effort by many people.. good
ones take even longer and cost way more to do well. I know; years ago I
worked in fine art book design and production.

But when people say - its not easy, not enough, time, people or money..I
simply asking 

Q1: How much time, people, money [quantify] do you think it needs to do
Zope docs _well_?

Q2: How many on this list are willing to pay $n, and if so how would/could
that help?
Not a criticism -  just trying to see what the scale of the problem or
solution is

>We're working on it, but remember this is an OPEN SOURCE project, which
>means that the community is encouraged to participate.  If you dislike a
>section of documentation, you need to be specific in what you need
>documented past "It sucks", exact examples you think would help, etc.

Yes. Yes. OpenSource and openReSource. It does not 'suck'. It is huge and
complex.
Good examples are as useful as not. I pointed to the new 'Python Essential
Reference, because that  IMHO is a pretty good close example to review...
as are many (but_not_all_ OReilly In-a-Nutshell editions. And some WROX books.

Back when people were bouncing around ideas for improving the zope.org
website I suggested a schematic 'map' of Zope with a poster version.

Anyone like to see this?
What should it contain?
When you explain Zope to someone over lunch, what do you draw on that
napkin to help?
What is the sketch/structure which shows the relationships between
hierarchical path inheritance and acquisition?
I would be more than willing to help build such a map and am asking for
some feedback from people here. so I can help..


ideas?
- Jason