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