Re: Documenting Packages for Future Developers

On 03/02/2009, at 1:01 PM, Mikko Ohtamaa wrote:

>
> >
> > I formerly thought we needed to explain how all parts of Plone fit
> > together, but now I realize the complexity of Plone and Zope makes
> > this too hard (and probably unnecessary) and a manual for each main
> > topic is fairly enough.
>
>
> I updated the list:
>
> http://www.openplans.org/projects/plone-documentation/list-of-manuals
>
> I dumped my culminated knowledge which should cover 90% of use cases  
> I have struggled as a developer. Now the list contains few bullets  
> and all we need to do anymore is to write those open :) I tried to  
> take both of the best sides "task based" and "reference based"  
> approaches when creating the list.

Thats a fantastic list mikko.
"Archetypes schema model" seems a little strange being in with zodb at  
the beggining. Also it would be good to have a place to explain the  
different kinds of in plone. Perhaps a forms overview before the forms  
chapter. The reason being is that concept of standalone forms vs  
content type forms is foriegn to most developers coming from a non CMS  
background and something us zope people take forgranted as making  
perfect sense. In Plone the story is even more complicated with TTW  
standalone forms such as PloneFormGen and TTW content types such  
as ... well still to come.
Perhaps
- Forms and content type overview
- Standalone forms (is there a better name?)
- Content types
>


> I also created a list of "stock" items which should be commented in  
> the Plone code itself and the appropriate developer manual generated  
> based on the source.
>
> Zope 3 has done good work with doctest based documentation approach.  
> This could be applied for Plone as well. They usually reside on PyPI  
> page. Example:
>
> http://pypi.python.org/pypi/zope.session/3.8.0
>
> I also urge the developers themselves to take this task. Development  
> falls beyound doc team core knowledge. Developers themselves should  
> come up with a proper manual which could be edited by docteam.
>

I think we need something that can be edited by both but this is the  
tricky bit. Some of that list is editorial and some reference material  
better taken directly from the readmes in the code. but the goal is  
one easy to read manual sitting on plone.org.

We have an existing solution for combining the two by using sphinx to  
generate content into plone.org from both module docs and editorial  
docs put in a module in the collective. but that means all editorial  
content is in rst files in the collective which hasn't so far been  
acceptable to the doc team.

Another option might be some kind of hybrid approach where we  
overwrite certain pages in the plone based manual using sphinx  
(perhaps using tags to indicate this) and the rest is free to be  
edited in plone.

I think if developers saw their doctest based docs incorporated into  
the developer manual they would naturally try much harder to make it  
make sense in that context.


> o/ volunteers
>
> -Mikko
>


------------------------------------------------------------------------------
Create and Deploy Rich Internet Apps outside the browser with Adobe(R)AIR(TM)
software. With Adobe AIR, Ajax developers can use existing skills and code to
build responsive, highly engaging applications that combine the power of local
resources and data with the reach of the web. Download the Adobe AIR SDK and
Ajax docs to start building applications today-http://p.sf.net/sfu/adobe-com