[Product-Developers] Re: Where does it hurt?

Martin Aspeli optilude at gmx.net
Sun May 18 13:33:09 UTC 2008


Hi David,

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 
> https://weblion.psu.edu/trac/weblion/browser/weblion/FacultyStaffDirectory/branches/homegrown-extensibility/examples/FacultyStaffDirectoryExtender 

Agree.

> 2. Task specific examples - Common Plone Programming Recipes 
> (http://plone.org/documentation/tutorial/manipulating-plone-objects-programmatically) 
> 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. 

Agree.

> 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)).

Agree.

> 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.
> 
> 
> Annotations
> 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 
documentation.

> SchemaExtender
> 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.

> Z3c.forms
> 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 
of documentation.

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 
Plone Conference?

>      - 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
> 
> Debugging/Profiling:
> For developers just getting into python, this can be challenging.

I think this requires more documentation. We have reasonable tool 
support here, I think.

Martin

-- 
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 mailing list