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
<[EMAIL PROTECTED]
<mailto:[EMAIL PROTECTED]>> 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
_______________________________________________
Product-Developers mailing list
[email protected]
http://lists.plone.org/mailman/listinfo/product-developers
