Re: Documenting Packages for Future Developers

The idea of a "what techniques where used in this product" documentation
is great. And like Dylan I think that the sections list of a developers
manual is the list to choose from (and George's is not too distinct, as
far I can see).

The topping: an inverse search to find products which employ a certain
method.

But how to encourage people to use it? Should paster put some doc stubs
into a product?

Markus

Dylan Jay wrote:
> 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
> 
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

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