Re: Documenting Packages for Future Developers

On Sun, Jan 4, 2009 at 7:06 PM, George L wrote:

> Take an example you gave:
>
> """
> This product creates two new content-types, FortuneCookie and FortuneSteak.
> For more info about content-types, check
> http://plone.org/docs/content-types
> """
>
> A brief statement would work fine for a basic Archetypes content type (and
> there should be a link to Archetypes tutorials specifically). But if it
> gets
> a little more complicated -- uses a custom validation chain, uses an event
> handler to trigger an action upon a workflow action, uses
> archetypes.schemaextender, etc. -- it's helpful to add a little more info
> about what other topics the developer has to go look up.
>

Creating such an exhaustive list of technologies used in each product is
cumbersome IMHO.

Aditionally, I see the process of looking for documentation more like a
"cascade" than like a plain list of things to learn. If the purpose of a
product is to create a content-type, the first thing a user should read the
content-types manual, and whenever he/she finds something in the manual
he/she doesn't understand well (workflow, events, etc.), look for more
information about that topic, ideally clicking on a link on the
content-types manual.

Naming conventions for a product structure (interfaces.py, browser, etc.)
helps a lot, too.

-- israel

------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs