[Product-Developers] Re: Plone Developer Cheatsheet

[Dylan Jay]

Daniel Nouri wrote:
> Thanks.  I think the new structure is definitely an improvement.
> 
> It looks a bit overloaded though.  There are 34 points in "Current best
> practices" without apparent order.  It's hard to find what you're
> looking for.
> 
> I believe what we want is a table of contents at the top, and one more
> level of structure.  I imagine something like:
> 
>   - Current best practices
>     - Python and development tools
>     - Installation and Infrastructure
>     - Zope Component Architecture
>     - Templates and CSS
>     - Content Types
>     - Views and Forms

+1 for that. please have a go at restructuring with those sub 
headings.... except I think you only get 2 levels with kupu :(

>   - Emerging best practices
>     - [maybe same as above, except that we leave out empty sections]

-1. Not comfortable with saying in advance whats going to be best 
practice. Dexterity etc can come along and make z2c.form obsolete before 
z3cform is commonly used for example. Who knows. The only reason I put 
that section there is so people who really want to put their fav 
competing technology in, has somewhere to put it.

>   - Obsolete practices
>     - ...

+1. Thats a better name.

> When I start working with Plone, I can work through the Current best
> practices from top to bottom, picking everything that's declared "must
> read" (alternatively: "beginner").  And by reading the "advanced"
> articles/links in "Templates and CSS" I can specialize in
> skinning/theming.  Relying on the implicit order of items for weight
> isn't structured enough.  Especially when you have more than one author.

So each item has a "level: begginer" etc associated with it? I'm ok with 
that. lets try it.

> Dylan Jay writes:
>> Daniel Nouri wrote:
>>> Dylan Jay writes:
>>>
>>>> JoAnna Springsteen wrote:
>>>>> Short term, sure but incredibly valuable. And if it puts us in a place
>>>>> where we can talk about having best practices, then I think that's a
>>>>> great place to be.
>>>>> Having best practices gives us a much clearer path on what to
>>>>> document. In a sense, it's a baseline. You have this one way of doing
>>>>> something and this is the way to do it. Easier to document and
>>>>> maintain that then a million methods for accomplishing the same goal.
>>>>> And no, that doesn't mean we only do it that one way and we rule out
>>>>> other methods. Definitely don't want to do it. But a best practice
>>>>> helps us teach people where to start, what they really have to know,
>>>>> and generally gives them a good foundation once they move on to more
>>>>> complex things or pursue other methods.
>>>>> I could go on but my entire point is, it's a conversation worth having.
>>>> Thats certainly my intent behind it.
>>>>
>>>> First we'll see how if there is conflict and how it can be
>>>> resolved. I'll suspect it will need email notification of changes to
>>>> really make this work (and I don't think openplans does this) so
>>>> people can see when someone makes an update that others disagree
>>>> about. Or alternatively, encourage people to discuss before replacing
>>>> things on the best practices list.
>>> So I started fiddling around with your document.  I have my little
>>> problem with putting z3c.form in "Not best practice".  If the argument
>>> is that it's "too early" let me tell you that my experience has shown
>>> that it's much more mature than zope.formlib.  If people who haven't
>>> looked at it decide that they don't want to learn it yet for whatever
>>> reason, they should call it "too early for me".
>> We have a problem in that formlib and z3c.form fill the same
>> purpose. Since it's a current best practice list both can't exist in
>> the same list.
>> Since formlib is need to create a portlet I figured it had to be in
>> the list. I also figured it had only just been newly integrated into
>> plone even if it's mature on z3.
>> Perhaps you should ask this list as a separate thread?
> 
> You don't need formlib for Plone 3 style portlets, you can also use
> z3c.form.

formlib is built in which would make it pretty confusing.
I think the way to promote its use is not through the cheatsheet but 
with advanced developers like on this list. Then when we all start using 
it and when its built into the core, then it will be best practice right?

> There's still an argument for preferring formlib over z3c.form in this
> document.  And that's that Plone itself uses formlib.  I think the
> "Emerging best practices" cover this kind of thing pretty well.
> (Compare with GS migration steps.)

see above.

>>> Propse: Add a section "Forms", pull out PloneFormGen, zope.formlib and
>>> z3c.form out of the their current sections and put them all there, side
>> I got rid of those headings. Now just 3 sections. "Best Practice",
>> "Depricated" and "Newer/Alternatives". Should be clearer what goes
>> where.
>>
>>> by side.  I don't like "Standalone forms" either, as neither
>>>  zope.formlib nor z3c.form specialize on "standalone forms", nor should
>>> their use within Plone be encouraged to be for standalone forms.
>> For plone best practice that is what they are good for, since AT is
>> the currently the best practice for doing content types.
> 
> AT is best practice for portal types in the CMF sense.  It's not best
> practice for objects with a slimmer interface.  Many products (like

So how do explain to a newbie whats a slimmer interface. When to use AT 
vs plone.app.content vs z3cform with annotations etc?
The idea with this document is you have to make the differences very 
explicit and clear that a beginner can easily pick between them. If 
there isn't a big enough difference then both can't be on the best 
practice list. We should be aiming to make that list as small as possible.


> CMFPlone) store objects in the ZODB that aren't subclassed from CMF
> types or AT, think simple records, tools.  For these simple objects it's
> misleading to say that Archetypes should be considered for add and edit
> forms.  In the end, I'd argue that "standalone forms" is bad naming.
> I'd use "forms libraries" and explain the details on when to use what.

I want to make the reasons clear and enumerated. put many clear use 
cases if you want (although hopefully just a few words for each).
A general framework should have many uses not one generic general use 
description IMO.
Also you can put a technology stack in the list.
I think that if the combination of z3cforms + annotations (or whatever) 
is a good alternative to AT then that deserves its own item.

Alternatively we can label each line by its use. but I'm trying to avoid 
that to reenforce the point of one use one technology.