[Framework-Team] Re: PLIP documentation

Martin Aspeli optilude at gmx.net
Sat Dec 22 13:59:05 UTC 2007


Andreas Zeidler wrote:
> On Dec 21, 2007, at 3:31 AM, Martin Aspeli wrote:

>> I just put some documentation on the implementation of PLIP 203 up  
>> on the PLIP page (http://plone.org/products/plone/roadmap/203).
> 
> hmm, i'm probably missing something, but the "implementation" sections  
> of that plip is still empty (when viewed both anonymously and logged- 
> in) and i kinda have the feeling i've read it all before...  anyway,  
> that's definitely a helpful thing to do, so thanks, potentially in  
> advance. :)

Well, I just amended/corrected the "proposal" section, so that it's now 
accurate and more complete.

>> I would encourage others to do the same! Perhaps the framework team  
>> should insist on some documentation?
> 
> there should indeed be some sort of documentation and/or hints to help  
> us with reviewing the bundles as this would probably shorten the time  
> needed immensely.  so thanks for the reminder, martin — i'm +1 on  
> making this a requirement.  not necessarily on the plip pages  
> themselves, a .txt that comes with the package, patches or buildout or  
> an email to this list would also be fine with me.

Well, informing the reviewers what they need to look at it is one thing; 
helping others who want to understand what's changed in 3.1 and how it 
affects them is slightly different. A .txt file in a bundle helps the 
former, but I think the PLIP page is the natural page to write out or 
provider pointers to the latter.

>> Short of producing or updating how-tos or tutorials on each new  
>> PLIP, this is the best way in which integrators and other developers  
>> can get wind of the changes we are putting into 3.1 and learn how to  
>> use them. Since many of the 3.1 PLIPs are aimed at integrators, I  
>> think this is an important part of the process, and one that we  
>> didn't do well enough with for Plone 3.0.
> 
> good point, so documentation on the plip pages is preferred! :)

This is an area where we've been pretty bad in the past, so it makes 
sense to try and tighten it up.

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