Re: Documenting Packages for Future Developers

Hi George,

I think the excellent work being done on creating a developers/ 
integration manual should solve this problem.
With a conical reference which is organised in terms of subjects you  
would be able to feel more secure in pointing to the relevant chapters  
(by name or url). The manual chapters I guessing will look something  
like that great list you sent  through (someone correct me if I'm  
wrong).

for instance your example might become

Refer to the development manual[1] and understand the following sections
- "2: Setting up a new product for development"
- "3.2: 3Creating new generic setup profiles"
- "3.3 Using the generic setup tool to import and export"
- "4.2: Using Five: creating utilities"
etc.

[1] http://plone.org/docs/manual/development/current

and if you wanted to be even more sure that they are reading the right  
advice then you could peg the documentation version too
[1] http://plone.org/docs/manual/development/3.2/

nb not sure of the actual urls.

With an official manual containing most of what you want to refer to  
it would only get more tricky when there are techniques which are  
newer or not "core" therefore not in the manual. Then you'd have to  
refer to documentation in the "knowledgebase" area but that should  
still have urls centered around subjects and since its editable by  
anyone it combining of documentation should happen more often so even  
there you should get a more conical description of the subject/ 
technique (like what happens with wikipedia).

On 05/01/2009, at 5:06 AM, George L wrote:

>
>
> 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


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