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. <div>
<br></div><div>How to present information to skimmers (reference style readers)</div><div>---------------------------------------------------------------------------------------------------<br></div><div>1. The best code examples are short, task specific and complete. I like <a href="https://weblion.psu.edu/trac/weblion/browser/weblion/FacultyStaffDirectory/branches/homegrown-extensibility/examples/FacultyStaffDirectoryExtender">https://weblion.psu.edu/trac/weblion/browser/weblion/FacultyStaffDirectory/branches/homegrown-extensibility/examples/FacultyStaffDirectoryExtender</a> </div>
<div>2. Task specific examples - Common Plone Programming Recipes (<a href="http://plone.org/documentation/tutorial/manipulating-plone-objects-programmatically">http://plone.org/documentation/tutorial/manipulating-plone-objects-programmatically</a>) is a great resource for me, though some of the examples may not be the new way of doing things.</div>
<div>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. </div>
<div>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)).</div>
<div>5. Each document should begin with a hyperlinked checklist of what should know already. <br><br><div class="gmail_quote">On Sun, May 18, 2008 at 6:05 AM, Martin Aspeli <<a href="mailto:optilude@gmx.net">optilude@gmx.net</a>> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">Hi guys,<br>
<br>
Following a long discussion with Dylan Jay (buried in another thread on Devilstick terminology), I thought I'd conduct an informal poll.<br>
<br>
==> As a customiser of Plone, or as someone wanting to build bespoke components that extend Plone, what do you find most confusing?<br>
<br>
I think this could fall into a few categories:<br>
<br>
- Areas where there's insufficient/poor documentation, but once you learn how to do something, it's clear how to proceed.<br></blockquote><div><br></div><div>Annotations</div><div>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. </div>
<div><br></div><div>In order to use annotations one must first be familiar with:</div><div>Interfaces/marker Interfaces and ZCML</div><div><br></div><div>SchemaExtender</div><div>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: <a href="http://plone.org/events/regional/plone-symposium-2008/schema-extender-extends-your-mind">http://plone.org/events/regional/plone-symposium-2008/schema-extender-extends-your-mind</a> (look for the video link at the bottom of the page) still very useful so thanks Erik Rose. </div>
<div> </div><div>Z3c.forms</div><div>I know these are early days for this.</div><div><a href="http://plone.org/documentation/how-to/easy-forms-with-plone3">http://plone.org/documentation/how-to/easy-forms-with-plone3</a>, When I do my first z3c forms based product I will be able to make an assessment.<br>
</div><div><br></div><div>Writing Tests</div><div>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.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
- Areas where there appears to be more than one approach, and it's not clear which one to choose<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>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.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
- Areas where Plone doesn't appear to have a good way to do something<br></blockquote><div><div>Debugging/Profiling:</div><div>For developers just getting into python, this can be challenging.</div></div><div><br></div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
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.<br>
<br>
Cheers,<br>
Martin<br>
<br>
-- <br>
Author of `Professional Plone Development`, a book for developers who<br>
want to work with Plone. See <a href="http://martinaspeli.net/plone-book" target="_blank">http://martinaspeli.net/plone-book</a><br>
<br>
<br>
_______________________________________________<br>
Product-Developers mailing list<br>
<a href="mailto:Product-Developers@lists.plone.org" target="_blank">Product-Developers@lists.plone.org</a><br>
<a href="http://lists.plone.org/mailman/listinfo/product-developers" target="_blank">http://lists.plone.org/mailman/listinfo/product-developers</a><br>
</blockquote></div><br></div>