Re: Documenting Packages for Future Developers

Israel Saeta Pérez wrote:
> 
> Are you saying you're explaining how plone works in your products? Why
> don't
> you just link existing documentation?
> 
> Regarding the inclusion of a list of neccessary knowledge to understand
> how
> the product works, I think this can only help, but could be time-consuming
> for the developer and too rigid.
> 

Like you said, either linking to existing documentation or letting someone
Google or search for support about specific topics is better than including
all the details. What I'm trying to do is include enough information so that
they know what to look for. That long list I sent is an overall list I'm
drawing from, but not what would be included in any single product. For
example, the example I gave for one product had the following:

- Standard product coding and file structure
- Standard Plone installation, including GenericSetup
- Install a specific tool or utility within a site: Zope2 tool in site root,
registered as a Zope3 utility
- Adding property sheets
- Code-level techniques: custom exceptions, helper classes and methods
- Zope3 coding techniques: including Zope3 utilities

Of these, this could be pared down further too. So now someone can go look
up Plone product installation / GenericSetup, property sheets, and Zope3
utilities.

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.

The main items in the large list I sent (mostly the leftmost indented and
second leftmost indented) was my sense of what the basic techniques would be
to list, without getting into too much detail. (For instance, there is a lot
of detail I wrote in "standard Plone installation, including GenericSetup,"
but it's just that phrase that would be used in actual product
documentation. All the details could sit in a different tutorial or link to
the existing documentation on this.)

So I was trying to get feedback on: (1) Is documenting a product like this
useful to help point developers in the right direction? (2) If so, what
would be a good list to draw the main topics/techniques from that is not too
detailed but not too general either?

As for how this relates to core documentation, I would guess that most of
the details are already there. I'd suggest (1) double-checking key
documentation is there, and (2) if this approach is helpful, adding as a
document "How to Understand an Existing Product" a list like this along with
links to the appropriate detailed documentation. Because most of the
documentation already exists, I don't think there needs to be a bunch of
trac tickets to keep track of it. I see it as a different purpose than a
"Quick Start" guide because that's about someone creating products it seems,
like forward engineering; this is helping people understand existing
products, like backward engineering, but it can link to a lot of the same
detailed documentation.

Peace, community, justice,
- George
-- 
View this message in context: http://n2.nabble.com/Documenting-Packages-for-Future-Developers-tp2107425p2109843.html
Sent from the Documentation Team mailing list archive at Nabble.com.


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