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.

Tuesday, February 12, 2008

My Visit to Philips Research

My most valuable experience from the visit is not about the technical problems being solved. In fact two of three labs i visited were dealing with some medical image processing, operated by physical scientists. Although radioactivity could still be understood, a pair of photons was too distant from me. The remaining project was trying to aim stroke rehabilitation using sensors and computers. During the lunch served around 1pm, we got opportunity talking with those senior researchers with background in physics. It was fun talking with them. A person who has received enough scientific training behaves somehow differently, when they consider problems. It is independent on any particular knowledge, but the insight on solutions, quick understanding of questions, and pragmatic way of problem solving.