[Product-Developers] Where does it hurt?
david.bain at alteroo.com
Sun May 18 12:25:11 UTC 2008
To put this in context, I consider myself a "reference" style documentation
reader. What this means is that, while I have read a lot of the
documentation, I haven't read all the documentation at Plone.org and I am
most motivated to read when I need to complete a task.
How to present information to skimmers (reference style readers)
1. The best code examples are short, task specific and complete. I like
2. Task specific examples - Common Plone Programming Recipes (
is a great resource for me, though some of the examples may not be the new
way of doing things.
3. We need to overemphasize key knowledge requirements. So documents like "5
things you MUST know to become productive in Plone - Interfaces, Utilities,
Adapters, ZCML, Generic Setup. This document would not be a b-org style
tutorial, it would briefly explain each item and show 3 examples of usage
for each technology. This would help to frame a user's understanding. I
think the closest tutorial to this was the five walkthrough (now marked as
outdated). To update that tutorial for today's needs, I would use examples
form other products and briefly discuss (on sentence), what problem was
being solved in the context of that product.
4. Developing/Extending Plone products today is so driven by Interfaces that
it MUST be in a newbie's face, but as simple as possible. A marker interface
is a "flag" that says "I'm now in the family of ...., I now have these
capabilities". Currently mention of interfaces is scattered throughout a few
tutorials (b-org, walking through five to zope 3, quadapter (embrace and
5. Each document should begin with a hyperlinked checklist of what should
On Sun, May 18, 2008 at 6:05 AM, Martin Aspeli <optilude at gmx.net> wrote:
> Hi guys,
> Following a long discussion with Dylan Jay (buried in another thread on
> Devilstick terminology), I thought I'd conduct an informal poll.
> ==> As a customiser of Plone, or as someone wanting to build bespoke
> components that extend Plone, what do you find most confusing?
> I think this could fall into a few categories:
> - Areas where there's insufficient/poor documentation, but once you learn
> how to do something, it's clear how to proceed.
while there is documentation I didn't appreciate the annotation
story/pattern immediately. When I first tried to use annotations in my
product I had two references, Martin's b-org tutorial and the quadapter
(Embrace and Extend) tutorial by Maurit Van Rees.
In order to use annotations one must first be familiar with:
Interfaces/marker Interfaces and ZCML
I had similar difficulty when learning about utilities and events and
archetypes.schemaextender. BTW... when learning archetypes.schemaextender I
found that the visual tutorial was very helpful but the lack of sound was
for the video link at the bottom of the page) still very useful so
thanks Erik Rose.
I know these are early days for this.
http://plone.org/documentation/how-to/easy-forms-with-plone3, When I do my
first z3c forms based product I will be able to make an assessment.
There is lots of documentation, but writing tests still don't feel
approachable. I know this is bad, but when I need to get code out the door,
I skip the testing step. Maybe I need more practice, maybe test creation
needs to be easier, don't know.
> - Areas where there appears to be more than one approach, and it's not
> clear which one to choose
My biggest difficulty at the moment is moving away from the
archetypes/archgenxml way of doing things. They are so valuable and the
approach to product development is so well defined (at least to me). I've
dabbled with bits of the z3 style the archetypes.schemaextender, browser
layers and generic setup, but I am yet to create a significant (from
scratch) z3 style product.
I think this will settle down with better documentation around the paster
way of doing product development, I now use paster/ZopeSkel for skin
> - Areas where Plone doesn't appear to have a good way to do something
For developers just getting into python, this can be challenging.
> Please keep replies as succinct and factual as possible. I'm really not
> interested in a winge fest by people who've been frustrated in the past. I'd
> much rather have constructive feedback on where the pain is and, if
> possible, suggestions for how to improve things.
> Author of `Professional Plone Development`, a book for developers who
> want to work with Plone. See http://martinaspeli.net/plone-book
> Product-Developers mailing list
> Product-Developers at lists.plone.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Product-Developers