Documenting PLIP changes

What started as an utopic idea has now become real! Over the last Plone releases, the documentation had become sadly outdated, because the people writing code for the new features of the product were faster than the people writing the documentation for them.

During the last Plone Conference the Plone Documentation Team was revived. It was time to start doing things The Right Way (TM). Our idea was to bind the development to the documentation, studying PLIPs after being approved by the Framework Team and updating and extending the documentation base accordingly before the new product version is released.

And finally, we did it for 3.3! So congrats to everybody who’s participated! I hope that in the future more people will chime in and we will improve our workflow for updating and testing changes in the documentation. Some ideas:

  • We can’t publish (make visible to everybody) the documentation for the new version before the new version is released, because it will confuse people. Next PHC version will likely provide us Working Copy Support so we will be able to edit documentation “privately” while keeping the old (stable) version of a page public.
  • We have to coordinate better with the PLIP implementors to write, review and verify the documentation. Proposed workflow:
    1. Make a list of affected docs. This list will likely include only documents in the official documentation area.
    2. Make a copy of them and find someone to document the changes. With Working Copy Support, thiw will no longer be neccessary.
    3. Ask the implementer of each PLIP to review the introduced documentation changes. Test them against a beta or release candidate release.
    4. After the final release, copy the contents of the copied articles back to the live ones, and delete the copies. With Working Copy Support, promote the changes to the public page.

Happy ploning to everybody!

I've read: Predictably Irrational

Predictably Irrational – The Hidden Forces That Shape Our Decisions, by Dan Ariely, is a best-selling book about sociology, with a special focus on behavioral economics. Here’s a quick resume of what I’ve learned from reading it:

  • Everything’s relative. We assess things by comparison. Use a decoy, something that’s very similar to another thing but notably worse, to make people choose the second option.
  • Anchors. We do anchor ourselves to initial prices, and make decisions based on our previous decisions. To set a new anchor on a product, make it feel diferent.
  • In order to make a man covet a thing, it’s only necessary to make the thing difficult to attain.
  • FREE! is a powerful word. Offer things for free to make people choose them.
  • Post the prices in a shop or bar to be visible before or after people get close to the ordering place in order to self-select them or not.
  • There are two different worlds: one under market norms and another under social norms. Don’t mix them.
  • We do procrastinate. Try to set deadlines for yourself and push other people to commit to their own deadlines.
  • You valorate more things when you own them. Try to think about them as a nonowner.
  • You can’t keep all doors (options) in your life open. Make decisions and close the ones you like the least or you can’t keep up with.
  • When we belive beforehand thatt something will be good, it generally will be good. Raise the expectations of the people to make them ejoy something more.