Hi All, <lots of small talk follows, scroll down to **** section for the main point of this email> I guess I have officially volunteered to write content for the new zope.org site in the zope 3 section. Part of that involves describing what zope 3 is in a concise manner. I realize there are probably a lot of different opinions about what zope 3 is, so I would like to solicit the community to provide me with some ideas of what zope 3 is to you. It doesn't have to be anything fancy or publishable, just a bulleted list of "what zope 3 means to me" would be fine. I will aggregate these ideas and try to present it in an easy to read form. I don't want to start any arguments about what zope 3, so let's wait until I have something written before we start arguing :). Besides giving the 10000 foot view of zope 3, there is also a section for zope 3 documentation on the new site, which should probably include detailed developer documentation along with tutorials, howtos, references, etc. Fortunately, a little known fact is that there is already a fair amount of up-to-date documentation about many zope3 packages in the form of doctests (some better written for end-user consumption than others). Few people know about this because the documentation is not aggregated anywhere (except for some bits on apidoc.zope.org). You have to know to look on svn.zope.org or pypi pages to find the rest of it. Rather than writing a bunch of new documentation on the new zope.org site from scratch, I would like to harness the existing documentation, and just publish it in a nice way. To this end I have taken a look at sphinx, the new documentation publishing tool used by python.org. In short, it looks really good, and I think we could use it for zope documentation. Here is my thinking: Keeping *lots* of documentation maintained in any CMS or wiki style website is hard, because the people writing the code want to maintain everything (including documentation) in one place: subversion. It is too much to ask every developer to update a website every time they make a change to the codebase, because the website lives in firefox, while the code lives in vim or emacs. But if the documentation lives with the code, updating the documentation can become part of the normal flow of writing software (just like writing tests is part of the normal flow). So ideally, all package specific documentation *including tutorials and other end user docs* should live along side the code in subversion. Now the trick is just publishing this documentation. ***** THE POINT OF THIS EMAIL IS BELOW ***** I would like to develop a buildout recipe that generates aggregated documentation for a package (like z3c.form) using sphynx and publishes it to the new zope.org website. I want updating of zope documentation on zope.org to be as easy as uploading a package to pypi: When you are ready to make a release of a package, you would then do: $ cd z3c.form/tags/2.0/ $ python setup.py register sdist upload $ ./bin/buildout $ ./bin/update-documentation You would then be able to go to http://www.zope.org/projects/zope3/documentation/z3c.form and see everything from developer docs, to tutorials, to how-tos, etc. What do people think of this idea and who wants to help me implement it this weekend? -- Paul Carduner http://www.carduner.net