Documentation for Plone products: some bad and good attitude

Times ago I wrote some notes about how to release Plone products. I think I can add some other information to that article, mainly about documentation.
The "documentation argument" is already in the old post (section "Deprecated README") but I want to talk about something different.

One time again: all those minor issues are what I find difficult to explain when I give training to customers that want to learn Plone development.

Let's talk about how documentation change when you release a new version of a Plone product!
HISTORY.txt / CHANGES.txt
Sometimes I surf the Cheeseshop because I need some non-Plone-Zope library and the first thing I miss of the Zope world is the lack of a changes history directly given on the Pypi page.

I've not a bad behavior warning about this obviously! I think that every other framework in the universe must follow the Zope and Plone community example (what I mean is: the history file being also part of the long_description egg option)!

Commonly when history file is well done can also help you to find new features or dependency version changes... this great (but: keep reading)!
README: uncomplete
There are good products (often, sadly, developer targeted product) that can give you great things but have very poor documentation. What I can say about them? This is wrong for me... nothing new. I never liked a simple description of the product, maybe with a sentence like "look at the code and tests".

One example: http://pypi.python.org/pypi/Products.contentmigration. A really good product with a poor documentation.
README: good at the first release, deprecated later
Another bad attitude is to create a good (great) README file at the first release, then never changing it again later (yeah, I know... I've already touched this argument but let's going deep).

One of the thing I don't like is when the HISTORY.txt file also became the source of documentation. Sometimes reading the HISTORY/CHANGES section of a product you can find additional information or features.
I mean: this is good, but not only in the HISTORY section!

When you learn this about Plone, you'll start to read also at the history section of the product you like, but this is sad. Why don't update also the README?

Why this happen? I don't know. Maybe for laziness, maybe because you think that this new little feature is not important... who knows?
Sometime I think that the problem is also consequence of the work of multiple developer. Maybe the Guru Plone Developer did the product first, the another Little Plone Developer added a tiny feature and he someway fear to update also the README file.

So: if you are a product developer, please update the documentation. If you like to use 3rd party products: look at the HISTORY.txt: you could find good news there.

Example: did you know that, when using LinguaPlone you can rely onto a Plone site root view (@@language-switcher) that will redirect you to the proper language folder? This can be found in the history of version 3.1a1.
Package numeration changes
Have you ever experienced this? You installed a product version x.y.z, and it worked. Then a x.y.z+1 is released. No documentation changes, few lines of code in the history, that simple says "we fixed this issue..."... but your upgrade was not so easy, or probably failed.
Looking at the source, you discovered that this release is really different from the one before.

You will suffer of this problems commonly only when you need to keep compatibility with older Plone releases. Another example (still related to Products.contentmigration): what is the last version you could use on Plone 3?
For what I know is the 2.0.1 version. The is also a 2.0.2 or 2.0.3 version (and you can think: this is only a minor release, it's better to keep it) but this will not work on Plone 3 anymore.

This is only a problem of how numbers are used in the release version: given x.y.z I like to:

• keep x for a deep technological change (for example: now your product will require PostgreSQL to work)
• keep y for a feature change or addition
• keep z only for bugfix

You see it? It's the same logic that Plone use!

What about a version that drop support of an old version of Plone?
Probably the most user friendly choice is to change the x number (Like LinguaPlone did: starting from version 4 and above you are warned that is only a Plone 4 compatible version... unluckily you need to go to the history section to read this! ),  maybe changing only y can be acceptable... but in my opinion not z!
Please, keep it for bugfix only!