The first day of Sauna Sprint was spent introducing new EESTEC people to Plone. Almost everyone got Ubuntu installed, there was a short crash course for IRC and then we started installing Plone.

We had a bunch of EESTEC students as a test subject and our goal was to map obstacles in the process of installing Plone for local computer for development. We got some interesting results.

The data was collected on whiteboard where everyone was free to express any problem he or she had during the installation. The advisors also monitored the user group for possible problems and made notes.

Aperture Science test subjects installing Plone in hope they’ll get a cake if they success

Good job, but the cake was a lie.

Plone is #%!!”€&! difficult, but we can fix it

The comments below are collected from the whiteboard.

Don’t make assumptions in the documentation – people are tabula rasa (i.e. how to use cd command and so on)

Documentation needed to install gcc, PIL dependencies etc. on OS level

No good instructions how to set-up Python with virtualenv (was being fixed in the sprint). Buildout actually does not work with the system Python out of the box: you need to break your OS http://stackoverflow.com/questions/5818100/buildout-tries-to-update-system-wide-distribute-installation-and-refuses-to-run

People try to run buildout by “cd bin ; ./buildout” – it does not work and the error message is confusing

Unified Installer – ZEO installation is broken (need clarification what was broken)

Detect Python version in buildout and don’t try to run on incompatible version

When creating first Plone site input field has label “Path identifier” – people try to enter Plone FS path there

README.txt in Unified Installer needs updates

ZopeSkel template plone4_buildout should autodetect the latest Plone version (now was 4.0.1)

Update the out of the box Plone installation front page to contain more developer friendly instructions too

plone.org/downloads: Show add-on version compatibility as the first item on the page – if now compatibility set warn that the compatibility is unknown (same kind of warning if no updates for one year)

Have an easy way to report broken packages

Force a process to improve add-on documentation in p.org, especially regarding installation. Only 1/5 themes was successfully installed by the test personel without guidance, mostly due to lack of instructions and version incompatibilities.

Some work in progress on PiratePad regarding the installation of Plone.

Evening program

We had Sauna time in Hervanta, student style. EESTEC lived up to their reputation as party animals.

Delicious pizza was baked, though the audience loudly disagree when the pizza was burnt enough to be eaten

Magic Toni Sause

Get developers  Subscribe mFabrik blog in a reader Follow me on Twitter

• Because of duck-typing, you should rigorously document how methods should be called (try epytext and its fields).
• Most open source Python projects do the exact opposite
• Even Python standard library is poorly documented and sets a very bad example (missing manual ???)
• Thus, programming in Python becomes nightmare of grepping through source code (the implementation) or stepping into it in pdb just to figure out how APIs should work (Plone/Zope, anyone?)

Should Python community stop in some point to focus on delivering better documentation instead of focusing on new features and goodies (like the syntax moratorium which was recently lifted)?

From my personal experience

• The best, and the only, person to document the code adequately is the person how originally wrote it
• Because the author already knows how to use the code he doesn’t need to care about the fact how to enable the code for other users.  Many libraries and projects are driven by “scratching your own need” mentality, not by “let’s make this a happy community” mentality. The exception is something like Facebook or Google whose sole purpose is to attract new users their platform bringing in new €€€.
• If you are developing a framework or community project make the documentation a requirement for deliverable and stick with it. If you let one person to skip one hour of writing documentation you are making 10 persons spending one hour figuring out how to use the damn thing.
• Doctests are not documentation. They are tests. They are extremely unreadable way to say “how I should use this thing”, because doctests are often executed in the context of test stubs which do not reflect connections to the other parts of the framework or real contexts.
• “Buy a book – it tells you everything” business model is not feasible in long run. Books get old. Books are not searchable. People don’t buy books.

The good documentation is a way to differentiate, and win, in the situation where there are competing frameworks. I believe the success of Django was mostly driven by its good documentation.

This points could be applied to other duck-typed, open source driven programming languages (PHP anyone?). With good documentation we can reduce the need of Valium recipes for everyone of us.

Get developers  Subscribe mFabrik blog in a reader Follow me on Twitter

Vote here.

• Backpacking with Plone: how our team has redefined North Lapland travel industry with Plone sites. I promise to bring a genuine Lapland snowball with me and toss it to the first person asking a question.
• Mad about mobile: How to turn your Plone web site to a mobile site in 15 minutes (* the actual time varies on the status of PyPi and buildouting speed). If you can’t afford iPhone 4 yet, I promise the site will be 100% functional on a 40$ budget phones also.
• Culture of good documentation: Plone is hated because newcomers cannot grasp how to customize it. I belive this is an attitude problem, not with the newcomers, but with module authors. This manual is now 86k words. If we can make it to go up to 100k words in the conference I’ll buy a beer everyone who participates the effort.
• The world outside Plone: Why there exist 13 600 000 Joomla! sites, but 20 000 Plone sites? Why single Joomla! freelancer-entrepreneur can make 250k€ a year alone? How we could make Plone more succesfully by learning what others are doing? Our team has some cross-system experience and we want to give you the best bits what others are doing right (and Plone might be doing wrong).

Vote here in the case you missed the link above.

Ps. If I am too boring I promise I will do only PHP/Joomla! jobs in the future, so vote me now or I will forever hold my peace :<

Get developers  Subscribe mFabrik blog in a reader Follow me on Twitter

It is still very much draft, but I assure you will find it useful. You will find it even more useful after you put in the answers for your own problems.

In my previous Plone developer documentation rant my flow of though was little abstract and I couldn’t clearly explain how I want the community to maintain this crucial piece of documentation.  This time I made a comic.

* How to get support

** How to update Plone Developer Manual

However, asking the same questions again and again, or asking the question in the first place, is undesirable way to proceed. A proper way to fix the problem would be have a proper documentation voiding the need to ask the question in the first place. Since documenting Plone API is a huge task, I propose the following to get things bootstrapped:

1. Wherever and whenever someone asks a question regarding Plone code development do not answer directly

2. Instead, write the example code snippet and commit it to https://svn.plone.org/svn/collective/collective.developermanual/trunk (collective commit access needed)

3. Give the link to the SVN trunk file as an answer This way we should slowly start building up a “developer reference” which covers the most common API use cases.

https://svn.plone.org/svn/collective/collective.developermanual/trunk is a mess. Do not care about this little detail. Just toss in your .txt files. The docteam and I will properly proof-read and structure it in the future. As soon as we code snippets keep flowing in I am happy!

Example

Here is how I helped some unlucky person struggling with DataGridFrield and created some documentation during the process.

Private email question:

I have been using your excellent DataGridField add-on on a projet, where as webmanager I add variable lists of information within an objet.  However now I would like to build a script that would insert new rows and content automatically : let’s say a User calls a specific objet ‘A’ from time to time, I would like to have a DataGridField that will record incrementally these calls (with columns like “when”, “how long”, “what result”) each time they are made, without the User having to do anything.

I tried to find an answer in the code but I’m not fluent enough in Python yet to understand everything I read.  Could you tell me how I could build that script or where shall I look for clues ?

Private email answer:

Please also read some guidelines I tried to come up for documentation.

I think the dicussion is mostly fueled by third party developers’ frustration with the current development documentation situation. Developing for Plone is difficult, since finding references, how tos and examples for those little things you need is very hard. This is a turn off for many developers who would otherwise use this great system – high developer learning curve and gaps in the documentation makes the system useless.

Points everyone agree are

• Plone development documentation is not good
• Sphinx is good for API documentation – already happening
• Contributors are needed

Points discussed are

• Should developer documentation be more open ended (Wiki-like). This covers
  • Developer manual
  • How tos and other misc. references
  • API documentation
• Mostly, it is not about generic end user, admin or system integrator or getting started documentation (here, here)

Pro wiki-like documentation stances

• It should be more open ended (here, here, here)
• It’s better to have something messy instead of nothing at all – the current approval process discourages contribution (here)

Con wiki stances

• It should not be open ended, since this results to messy documentation (here, here)
• There should be less plone.org documents (here)
• Wikis are bad (here)
• Incomplete wikis are discouraging (here)

Let’s wait and see where this goes.