Re: [Plone-docs] AT Developer Manual

[Marco De V. <sta...@sp...>]

Il 29/11/2006 10:19, Raphael Ritz ha scritto:

> 'mkdir' alias:
>      customization hook for manage_addFolder,
>      used by some folderish types (WebDAV/FTP)
> 
> 'gethtml' alias:
>      customization hook for manage_FTPget,
>      used by some contentish types (WebDAV/FTP)
> 
> 
> Isn't it pretty obvious what that means?

Not to me.
IMHO these descriptions are not clear for a newbie, and they also don't 
give any hint to why have those aliases been used in the InstantMessage 
product.

Trying to understand them... "mkdir" is an alias you can use to 
customize the manage_addFolder method, so I was not far away... but why 
are we using it for a non-folderish type? And what does the "WebDAV/FTP" 
in parentheses mean? Is it a method which is only called when accessing 
content through these two protocols?

"gethtml": ok, you can use it to customize the manage_FTPget method, but 
what's the purpose of this method? Why are we using it here?

I know I'm annoying, but I think that developer documentation should 
teach how to do things the right way, and not just show some code to 
copy&paste blindly. Do you really think that every new developer will 
spend the time needed to dig the Plone/AT/CMF/Zope code and find out 
what those aliases and methods mean? They will just copy&paste.
The 10 minutes it takes for an expert developer to better explain this 
stuff can save hours to new developers, and most importantly can help 
growing up *better* developers ;).

On a side note, I'm not saying that all current documentation has this 
fault... for example, I think that the RichDocument tutorial is very 
good in this respect: it often gives useful pointers and hints to better 
understand what's going on.

-- 
Ciao,
   Marco.