[Product-Developers] Re: Where does it hurt?
optilude at gmx.net
Sun May 18 13:33:09 UTC 2008
David Bain wrote:
> 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.
I think a lot of people are like this.
> 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.
Agree, we need more "snippets" or "cookbook" type resources.
In the past, we've talked about supporting this as a special type of
object in the PloneHelpCenter. I wonder if it's worth reviving this idea.
> 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 extend)).
> 5. Each document should begin with a hyperlinked checklist of what
> should know already.
Agree very much.
> On Sun, May 18, 2008 at 6:05 AM, Martin Aspeli
> <optilude at gmx.net
> <mailto: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
Annotations are a powerful concept, and probably deserve some specific
> 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
> annoying: http://plone.org/events/regional/plone-symposium-2008/schema-extender-extends-your-mind
> (look for the video link at the bottom of the page) still very useful so
> thanks Erik Rose.
Cool. I think at.se deserves a proper tutorial.
> 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.
Agree. This is still quite early, as you say, but it will require a lot
The good news is that the intrinsic (non-Plone-specific) z3c.form
documentation is extensive: http://pypi.python.org/pypi/z3c.form.
> Writing Tests
> 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.
Remind me never to use your code. ;-)
What's wrong with the updated
http://plone.org/documentation/tutorial/testing and the associated
example.tests package that Philipp and I developed for the previous
> - 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.
Don't! Seriously. Every time someone says to me that they think they
have to do this, I tell them not to.
> 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.
Don't. Seriously. Until we make it easier for you to do it, why do you
feel that you have to?
> I think this will settle down with better documentation around the
> paster way of doing product development, I now use paster/ZopeSkel for
> skin development.
I use ZopeSkel to start Archetypes product with the 'archetype'
template. If you don't use ArchGenXML, it's a good place to start.
> - Areas where Plone doesn't appear to have a good way to do something
> For developers just getting into python, this can be challenging.
I think this requires more documentation. We have reasonable tool
support here, I think.
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book
More information about the Product-Developers