Finding documentation for Zope/Plone

The process of learning Zope can be a bit, uh, difficult. The documentation is plentiful, but not consistent, or located in a single spot. There are sites like cmf.zope.org which claim to have out of date information but which provide no links to the current version or any indication if there actually is a current version.

Last week some folks started yet another effort at creating a universal zope documentation repository at zopewiki.org. So far it’s only got 200 pages of documentation.

Other places to get documentation is zope.org which is a massive but not particularly easy to navigate site. The plone people have their own site and their navigation and documentation tend to be much better. One thing that impressed me when learning about Plone as a free software project is only one of the nine teams which make up the project is actually related to programming. The other 8 are all about making the system useable in various ways. It helps that almost all plone developers are paid to work on plone because they use plone to do web consulting.

Often the only place to find documentation is in the code. Python is fairly readable and programers use this to be lazy and not write good comments or documentation. Sometimes if the programmer was good she wrote unit tests. If they exist they are the best examples to work from. Unfortunately even despite there being thousands of unit tests in plone, they don’t go nearly deep enough in to the functionality. I get the impression that most of the code was not written in a test first manor. Sometimes the programmer put some documentation in their ‘product’ folder in either a help or docs sub folder. Most of this documentation exists ONLY in the product and can’t be found online except in web cvs archives. It’s worth reading if it exists.

Another source for directions to find documentation are the irc channels. Most useful is #plone on irc.freenode.net. There is a #zope channel which is according to the zope irc junkies dead. There are also a few plone mailinglists which get more email than anybody would want to read. They are useful for searching the archives.

Oh, i almost forgot to mention, there are zope and plone books. I’ve found them to be mostly useless. Not because they don’t cover a lot, just because they mostly do it from an end user or site administrator perspective. They don’t talk about or address issues somebody faces when developing CMF Products.

My primary problem in finding useable documentation is, i believe is that i refuse to use the point and click ZMI. All of our development must be checked in to a version control system, we must be able to have it install and setup out of the box, we must have unit tests (we use some doctests too) which were written before the code and which are through. There are some very good reasons for these requirements, but they don’t fit the mode of the average user. Welp, it’s lunch time, and spring in Rome, i’m going to grab a sandwich and take a walk in the park.