Re: Help document Plone's API

Israel Saeta Pérez wrote:

> I'd love to participate on that but I currently don't have the time
> and won't have it until late June due to my exams. :-/

I suspect we won't get anything moving until then, so if you do want to 
own this, that'd be great. ;)

> I'm not sure if a big tutorial like the "Managing Plone Objects
> Programmatically" is the best approach here. Currently we're trying to
> refactorize existing docs into manuals, more or less by topics, and
> each of these manuals could include one or more pages describing the
> API. For example, the WorkflowTool API could be explained inside the
> workflow manual. What do you think about that?

That doesn't solve the problem.

We indeed should describe relevant practices inside the specific 
manuals. And we should indeed have tutorials/manuals that go in depth 
into a topic. But that's not what I'm getting at here.

People need a more concise overview to find examples of the most common 
code patterns. That "manipulating objects programatically" is, I 
suspect, one of the more read tutorials on plone.org. It's not meant to 
*explain* every topic. It's just meant to give you a reference for how 
to get things done that you can keep in one place and keep referring 
back to. The lack of this type of reference is holding us back, and has 
been for years.

> In the future I would like the API documentation to be generated
> directly from the doctests and sphinx or similar tools would be very
> helpful here.

That's a different issue again. It'd be great to expose this. However, 
there's too many doctests and interfaces and no structure (other than 
the arbitrary package structure of the code they're bundled with) 
that'll help people find what they need. If you look at that mindmap, 
many of the groupings sit across three or four packages.

> -- israel
> p.s. Martin, we got a portlets manual for developers that needs
> review... would you like to take a quick look at it?

Yes - email me. :)

Cheers,
Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book


------------------------------------------------------------------------------
Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT
is a gathering of tech-side developers & brand creativity professionals. Meet
the minds behind Google Creative Lab, Visual Complexity, Processing, & 
iPhoneDevCamp asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com