[Plone-docs] Re: When will Plone stop being bleeding edge?

[Martin A. <opt...@gm...>]

On Fri, 26 Aug 2005 09:59:33 +0100, N.Davis  
<nd...@le...> wrote:

>
> Thank you all for very constructive replies.
> It occurs to me we could have documentation sprints....

A good idea, actually, if we can generate enough interest.

> Martin, your list of what needs documenting was very helpful and also it  
> shows what things we ought to be learning, that we didn't know we needed  
> to know, IYSWIM. ;-)

I don't know what IYSWIM is, but if you wanna get wet, go right ahead.

I think the "how to conceptualise Plone" tutorial will be the most  
valuable one, followed by the "how to customise". This stuff is available  
elsewhere, but we need a single point of entry for people who look at  
Plone and go "wtf". I have the structure for this in my head, I just need  
to get some time to do it right. Hopefully in September.

> We have got Andy Mackay's book and I find it very helpful and thorough.
> The MySite tutorial is great though I still have to explore more with it.
>
> I think challenges in learning this are :
>
> 1. Learning Plone/Zope/Python all at the same time. This is quite a lot  
> but not something specifically to be addressed by Plone docs, and I did  
> find Guido's Python tutorial to be great.

Yes. Again, the "how to conceptualise" should help put this stuff into  
perspective, at least. There is a learn-as-you-go mentality that works  
quite well when you've crossed the initial barrier. We just need to lower  
that barrier.

> 2. Getting used to multiple inheritance. It seems really weird at first  
> when you've done years with single inheritance. Things seem chaotic and  
> not making sense, but then you get used to it. Exploring the list of  
> base classes in DocFinderTab helps a lot here.

Thanks for that - I started with C++, but I appreciate many people who  
have backgrounds in Java, C# etc. find multiple inheritance problematic.  
Again, the "how to conceptualise" tutorial should include some background  
of how Zope classes end up inheriting what they have.

> 3. Contradictory information about customising. There is so much  
> documentation that talks about using the ZMI to change things when this  
> is apparently a bad idea for maintainability. I have now written a  
> product that applies our branding by having custom stylesheets, footer  
> etc. I really don't want any information about how to customise through  
> the ZMI if thats not the best way. This all seems like irrelevant info.

Yes! This is why I want to write a "how to customise" tutorial, and also  
expand the Plone best practices.

Customising through the ZMI is sometimes the only way (if you don't have  
filesystem access), sometimes the quickest way (if you're only doing minor  
tweaks), sometimes the lazy way, and too often the way that's easiest to  
describe in a how-to. :-( We should have a definitive tutorial and this  
and link to it. All in my plan :)

> 4. Where does Archetypes really fit in to the underlying architecture?  
> OK it started as CMFTypes, then became Archetypes above Plone, now its  
> sort of gone back down at a lower level as ATContentTypes. I can see why  
> this has happened and its progress, if a bit confusing sometimes. ;-) I  
> am still trying to get the overall architecture picture in my head.

Right. Again, the "how to conceptualise" should explain this. It's not so  
complicated. You have, from top to bottom:

Plone  ---> ATContentTypes (product defining the types used in Plone)
  |             |
  |             |
  |             V
  |         Archetypes (frameworks to make making new types easy)
  |             |
  |             |
  |             V
  +----------> CMF (underlying framework, also includes ability to make  
types, more complex)
  |             |
  |             V
  +----------> Zope (application server, base platform)
  |             |
  |             V
  +----------> Python (programming language)

> 5. Learning sequence. Some people would say the logical way (and in fact  
> this is the chronological way experienced people have learnt) is to  
> learn Python then Zope , DTML, ZPT, then CMF, then Plone, then  
> Archetypes.

Stay away from DTML, we harly ever use it.

> In practice, now, a newcomer might go straight to working on an  
> Archetypes class. So suddenly you need to know Archetypes, Plone, ZPT,  
> Zope, ZCatalog all at the same time without linking how they sit on top  
> of each other. ;-)

This will depend on style and need. I think it's more important to give  
people the power of knowing where to look than to give them a long list of  
things to read. http://plone.org/documentation/how-to/read-documentation  
is an attempt at this. Please offer feedback if you think this document is  
not sufficiently clear or is missing some resources.

Martin

-- 
(muted)