Thursday, November 13, 2008

Two ways to make bad documentation

Since our group are going to switch to a modern Content Management System (CMS), I am investigating candidate products. Two promising choices are Apache Lenya and Plone. I have to say that going deep into neither of the two is pleasing.

Lenya suffers from lacking documentation. Till now, not a single book is published about it. Furthermore, it is migrating to version 2.0, which renders most of existing documentation useless. At the time of writing, there is no complete manual on the Lenya site. However, because of the conceptual simplicity, Lenya is easier to understand in my opinion. The use of Apache Cocoon also adds to the value of Lenya.

It is just the other side for Plone. We are just flooded by documentations, which are full of specific terminology known only inside the community. Again, almost all the existing documentations are out of date for Plone 3. Furthermore, i have a feeling that the document authors are not really serious programmers. They tend to use quite informal and inaccurate descriptions. Maybe that is the way the supporting staff make money. Plone gives me a feeling of SAP, which always requires 2nd development that is more interesting to service staff than to users.

Lessons learned:
- documentation should be up to date and understandable:
There should be at least one entry level sample that can be run. If some special terms really have to be used, define them first. Finally, combining documentations for both front-end users and developers would just be confusing.
- Simplicity is much better than complexity
There should be some overview over the architecture or main mechanism. Although a framework can be rather complicated, there should be some central ideas that are so simple that humans can bear in mind.

1 comment:

Alexander Limi said...

I agree with most of your points, and you'll be happy to know that our priorities for Plone documentation are:

- Reduce the amount of redundant and outdated documentation

- Have developer documentation embedded and generated from the software itself using Sphinx

Of course, these things take time, and it's not the most rewarding task. Please help out if you can.

The upside is of course that Plone has quite a number of books out — and with two more (Practical Plone and Theming Plone) coming out very soon. :)