Documenting Packages for Future Developers
|
|
| 1 2 |
|
George L
()
Documenting Packages for Future Developers
|
|
||||||||||||
|
Hi all,
I have a large number of custom products and eggs that I have made for a Plone web site project that I am now documenting. Because eventually I will not be around to maintain the software, I am working to make it as clear as possible to the next tech people how to maintain the software and make changes small and big. I am sharing my thinking on this to get feedback and because it may be helpful to other people. Much of the documentation I have seen before falls under "Learn about how to create a product." The major perspective informing my documentation work right now is "Learn how to understand an existing product and be able to make some changes to it ... including how to know what exactly about Plone/Zope you need to learn in order to understand the product, without having to learn everything!" As an example, one product I use has documentation that says its code uses the following techniques: - 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 I don't bother explaining in that product's documentation all the details of what coding for a standard Plone installation looks like, what property sheets are, or what a Zope3 utility is -- that's where a developer can go learn more if they don't already know. I try to strike a balance here. Someone might look at this and scoff and say, "What? Any real Plone developer should know what property sheets are," or "Any real Plone developer should know how to use Zope3 utilities." But to me it seems that the number of Plone developers out there who know all the different techniques isn't huge, and it took me a long time to learn these techniques. So without dumbing down the documentation to explain every detail, the documentation at least gives a general overview of some of the major techniques someone needs to know to understand the code. So tada -- this is my general comprehensive list right now of techniques which I draw these shorter bullet points from. Almost every line of code in my product is captured somewhere in this list. It would be great to hear feedback on using a list like this, and what people think about this list in particular. - Standard product coding and file structure. This may include the following: - README.txt - Describes product - TODO.txt - Software developers’ notes on remaining tasks - version.txt - A number indicating the version - This information is used by Plone’s “quick installer” and possibly CTMigrations - __init__.py - Zope initialization: initializes a product so that Zope can detect it - Initialize content types and Archetypes content types so that Zope and Plone can detect them - Initialize tools so that Zope can detect them - Initialize skin directories so that Zope can detect them - config.py - Standard global variables: PROJECTNAME, GLOBALS, SKINS_DIR, DTML_DIR - Project-wide permissions - Project-wide permissions using wirePermissions methods - A uniform way to wire permissions during initialization so that many of them dynamically include the project name as part of the permission name (e.g., “FooEvent: Add FooEvent”) - Other project-wide constants - ToolNames.py - Constants that include very basic information describing site tools, stored in a standard place - FooTool.py - Files with definitions of site tools - refresh.txt - A file that allows a software developer to reload a product after making some changes to it, without restarting the entire site (this technique is out of date now) - LICENSE.txt - License information for the product - devel/ - A directory used to store additional software development work - tests/ - A directory that stores tests for the product - skins/ and subdirectories - Skins directories with templates, scripts, images, and other files - dtml/ or www/ - DTML pages used especially for ZMI management screens - Zope3 files - When Zope3 techniques are used, they will also be described specifically in a product’s documentation - configure.zcml, implements.zcml, interfaces.py, browser/, and browser/interfaces.py - Standard Plone installation, including GenericSetup - Extensions/, Extensions/__init__.py and Extensions/install.py - The Extensions/ directory and __init__.py file allow install.py to be readable - install.py allows the product to be installed in a Plone site - Typical installation procedures: - Install product dependencies - Run a GenericSetup extension profile - Write to an installation log - GenericSetup extension profile - Typically: - registered in __init__.py - run in Extensions/install.py during installation in a Plone site - stored in profiles/default - Basic skins and templates - Add a skins directory in a Plone site - Often using a GenericSetup profile - (Specify:) Templates; scripts; controller page templates, scripts, and validators; images - Basic template techniques – TALES logic, macros - (Advanced:) Using Zope3 views inside of templates - (Advanced:) Overriding templates, scripts, css, etc. [also see “theme” section] - Add basic Archetypes content types - Basic skins and templates - Content permissions (look at rolemap.xml for YWAEvent – are there multiple ways to do this?) - Catalog and metadata (GenericSetup) - Files with definitions of Archetypes content type classes and schema - Archetypes class definitions, including type names, icon, schema, global_allow, _at_rename_after_creation, __implements__, validators, custom mutators and accessors, miscellaneous methods - Archetypes schema definitions - Initialize and register type (within definition file and activated by product’s __init__.py file) - content/__init__.py: Import content types for easier access - Workflow associations - Add type through GenericSetup - Advanced content type customization: - RichDocument attachment types - Nonstructural folder - Customize schema after the fact - ISchema - Event handlers - Extension fields - Custom validation chains - Field sharing and overriding fields - Install a specific tool or utility within a site - Zope2 tool in site root - Icon file in product directory or skin - Subclass the appropriate base classes (e.g., SimpleItem) - Declare id, meta_type, actions, security declarations, management tabs and corresponding DTML files - Possibly create classes of Zope2 items to store within tool - Install tool during software installation in Plone site (using GenericSetup) - Zope3 utility - Register utility in local component registry during software installation in Plone site (using GenericSetup) - Zope3 browser view - configure.zcml, class, template - Declare Zope2 and/or Zope3 interfaces - Provide a theme - Viewlets - Create new viewlets - Override viewlets - Reorder viewlets - Hide viewlets - Connecting viewlets with theme specific interfaces - Theme specific interfaces - Skin selections - Overriding templates, scripts, css, etc. - View templates - Plone admin templates - Custom software templates - base_properties - Stylesheets - Possibly using portal_css - Custom css for theme - Site setup - Portal factory - Calendar workflow states - Portal actions - Portal action tabs (GenericSetup) - Site action tabs (GenericSetup) - Members - Kupu - Portlets to display - Versioning - Mailhost - Property sheets - Change site properties and property sheet properties (GenericSetup) - Security (GenericSetup) - Type info - Calendar – types to show - Content rules - KSS (templates and GenericSetup) - Install custom workflows - Change skin selection settings (default skin, add skin directories to all skin selection names) - Set up skin in install.py (using setupSkins in utils.py?) - Add external method - Basic site elements - Property sheets - Basic permissions - Workflows - {More?} - Extending basic site elements - Adding property sheets or adding properties to existing property sheets (using GenericSetup) - Advanced permissions - New workflows - {More?} - Add control and configuration panels - Plone control panel - Action icon (GenericSetup), configlet (GenericSetup) - Code-level techniques - Custom exceptions - Helper classes and methods, including utils.py - Store variables in module - External method - Importpdb - Zope3 coding techniques - Zope3 utilities - configure.zcml - implements - utility - Interfaces - Event handlers - Browser views, pages, adapters - Use other custom software tools: [these are products I created that other products use] - CTMigrations - CTImportUtility - CTRoleTuner - Create new setup handlers - Filename, XML adapters, configure.zcml to register XML adapters, helper import/export methods, helper methods, define import steps using GenericSetup import_steps.xml - Advanced site setup based on custom software - communitytechnology.newsletter [an egg I created that gets used in site setup] - Miscellaneous - Special: register fonts [using reportlab] Peace, community, justice, Peace, community, justice, - George |
||||||||||||||
|
vedaw
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
I can see a lot of this being incorporated into our core documentation.
There's a lot to dig through here, and I'm wondering if we turn this into a series of tickets in Trac for each editor to disseminate? It looks like there's some good quickstart material here, too. George, maybe you'd be interested in helping us figure out where some of this information would fit in our new manual structure? - Veda On 1/3/09 3:38 PM, "George L" <[hidden email]> wrote: > Hi all, I have a large number of custom products and eggs that I have made > for a Plone web site project that I am now documenting. Because eventually I > will not be around to maintain the software, I am working to make it as clear > as possible to the next tech people how to maintain the software and > make changes small and big. I am sharing my thinking on this to get feedback > and because it may be helpful to other people. Much of the documentation I > have seen before falls under "Learn about how to create a product." The major > perspective informing my documentation work right now is "Learn how to > understand an existing product and be able to make some changes to it ... > including how to know what exactly about Plone/Zope you need to learn in order > to understand the product, without having to learn everything!" As an > example, one product I use has documentation that says its code uses the > following techniques: - 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 I don't bother explaining in that product's documentation all the > details of what coding for a standard Plone installation looks like, what > property sheets are, or what a Zope3 utility is -- that's where a developer > can go learn more if they don't already know. I try to strike a balance > here. Someone might look at this and scoff and say, "What? Any real > Plone developer should know what property sheets are," or "Any real > Plone developer should know how to use Zope3 utilities." But to me it seems > that the number of Plone developers out there who know all the > different techniques isn't huge, and it took me a long time to learn these > techniques. So without dumbing down the documentation to explain every detail, > the documentation at least gives a general overview of some of the > major techniques someone needs to know to understand the code. So tada -- > this is my general comprehensive list right now of techniques which I draw > these shorter bullet points from. Almost every line of code in my product is > captured somewhere in this list. It would be great to hear feedback on using a > list like this, and what people think about this list in particular. - > Standard product coding and file structure. This may include the following: > - README.txt - Describes product - TODO.txt - Software developers¹ > notes on remaining tasks - version.txt - A number indicating the > version - This information is used by Plone¹s ³quick installer² and > possibly CTMigrations - __init__.py - Zope initialization: initializes a > product so that Zope can detect it - Initialize content types and > Archetypes content types so that Zope and Plone can detect them - > Initialize tools so that Zope can detect them - Initialize skin > directories so that Zope can detect them - config.py - Standard global > variables: PROJECTNAME, GLOBALS, SKINS_DIR, DTML_DIR - Project-wide > permissions - Project-wide permissions using wirePermissions methods - > A uniform way to wire permissions during initialization so that many of them > dynamically include the project name as part of the permission name (e.g., > ³FooEvent: Add FooEvent²) - Other project-wide constants - ToolNames.py > - Constants that include very basic information describing site tools, stored > in a standard place - FooTool.py - Files with definitions of site tools > - refresh.txt - A file that allows a software developer to reload a > product after making some changes to it, without restarting the entire site > (this technique is out of date now) - LICENSE.txt - License information > for the product - devel/ - A directory used to store additional software > development work - tests/ - A directory that stores tests for the > product - skins/ and subdirectories - Skins directories with templates, > scripts, images, and other files - dtml/ or www/ - DTML pages used > especially for ZMI management screens - Zope3 files - When Zope3 > techniques are used, they will also be described specifically in a product¹s > documentation - configure.zcml, implements.zcml, interfaces.py, browser/, > and browser/interfaces.py - Standard Plone installation, including > GenericSetup - Extensions/, Extensions/__init__.py and > Extensions/install.py - The Extensions/ directory and __init__.py file > allow install.py to be readable - install.py allows the product to be > installed in a Plone site - Typical installation procedures: - > Install product dependencies - Run a GenericSetup extension profile > - Write to an installation log - GenericSetup extension profile - > Typically: - registered in __init__.py - run in > Extensions/install.py during installation in a Plone site - stored in > profiles/default - Basic skins and templates - Add a skins directory in a > Plone site - Often using a GenericSetup profile - (Specify:) Templates; > scripts; controller page templates, scripts, and validators; images - Basic > template techniques TALES logic, macros - (Advanced:) Using Zope3 views > inside of templates - (Advanced:) Overriding templates, scripts, css, etc. > [also see ³theme² section] - Add basic Archetypes content types - Basic > skins and templates - Content permissions (look at rolemap.xml for YWAEvent > are there multiple ways to do this?) - Catalog and metadata > (GenericSetup) - Files with definitions of Archetypes content type classes > and schema - Archetypes class definitions, including type names, icon, > schema, global_allow, _at_rename_after_creation, __implements__, validators, > custom mutators and accessors, miscellaneous methods - Archetypes schema > definitions - Initialize and register type (within definition file and > activated by product¹s __init__.py file) - content/__init__.py: Import > content types for easier access - Workflow associations - Add type through > GenericSetup - Advanced content type customization: - RichDocument > attachment types - Nonstructural folder - Customize schema after the fact > - ISchema - Event handlers - Extension fields - Custom validation > chains - Field sharing and overriding fields - Install a specific tool or > utility within a site - Zope2 tool in site root - Icon file in product > directory or skin - Subclass the appropriate base classes (e.g., > SimpleItem) - Declare id, meta_type, actions, security declarations, > management tabs and corresponding DTML files - Possibly create classes of > Zope2 items to store within tool - Install tool during software > installation in Plone site (using GenericSetup) - Zope3 utility - > Register utility in local component registry during software installation in > Plone site (using GenericSetup) - Zope3 browser view - configure.zcml, > class, template - Declare Zope2 and/or Zope3 interfaces - Provide a theme > - Viewlets - Create new viewlets - Override viewlets - Reorder > viewlets - Hide viewlets - Connecting viewlets with theme specific > interfaces - Theme specific interfaces - Skin selections - Overriding > templates, scripts, css, etc. - View templates - Plone admin > templates - Custom software templates - base_properties - > Stylesheets - Possibly using portal_css - Custom css for theme - Site > setup - Portal factory - Calendar workflow states - Portal actions - > Portal action tabs (GenericSetup) - Site action tabs (GenericSetup) - > Members - Kupu - Portlets to display - Versioning - Mailhost - > Property sheets - Change site properties and property sheet properties > (GenericSetup) - Security (GenericSetup) - Type info - Calendar types > to show - Content rules - KSS (templates and GenericSetup) - Install > custom workflows - Change skin selection settings (default skin, add skin > directories to all skin selection names) - Set up skin in install.py (using > setupSkins in utils.py?) - Add external method - Basic site elements - > Property sheets - Basic permissions - Workflows - {More?} - Extending > basic site elements - Adding property sheets or adding properties to > existing property sheets (using GenericSetup) - Advanced permissions - New > workflows - {More?} - Add control and configuration panels - Plone > control panel - Action icon (GenericSetup), configlet (GenericSetup) - > Code-level techniques - Custom exceptions - Helper classes and methods, > including utils.py - Store variables in module - External method - > Importpdb - Zope3 coding techniques - Zope3 utilities - configure.zcml > - implements - utility - Interfaces - Event handlers - Browser > views, pages, adapters - Use other custom software tools: [these are products > I created that other products use] - CTMigrations - CTImportUtility - > CTRoleTuner - Create new setup handlers - Filename, XML adapters, > configure.zcml to register XML adapters, helper import/export methods, helper > methods, define import steps using GenericSetup import_steps.xml - Advanced > site setup based on custom software - communitytechnology.newsletter [an egg > I created that gets used in site setup] - Miscellaneous - Special: register > fonts [using reportlab] Peace, community, justice, Peace, community, > justice, - George -- View this message in context: > http://n2.nabble.com/Documenting-Packages-for-Future-Developers-tp2107425p2107 > 425.html Sent from the Documentation Team mailing list archive at > Nabble.com. ---------------------------------------------------------------- > -------------- _______________________________________________ Plone-docs > mailing > list [hidden email] https://lists.sourceforge.net/lists/list > info/plone-docs ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by George L
On Sun, Jan 4, 2009 at 12:38 AM, George L wrote:
Are you saying you're explaining how plone works in your products? Why don't you just link existing documentation?
Like Veda has already pointed out, this is very interesting material to help us organizing plone.org manuals and quickstarts. 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. Maybe describing what's the purpose of the product and linking documentation where neccessary would have a similar effect, e.g.: """ This product creates two new content-types, FortuneCookie and FortuneSteak. For more info about content-types, check http://plone.org/docs/content-types. """ """ This product adds a new (zope 3) view to the News Item content-type using GenericSetup. For more info about z3 view, see http://... and for more info about GS, see http://... """ However, searching appropiate keywords in Google should work for most readers, too. :-) -- israel ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
|
George L
()
Re: Documenting Packages for Future Developers
|
|
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 |
||
|
Dylan Jay-4
()
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 > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Markus Bleicher-4
()
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 >> [hidden email] >> https://lists.sourceforge.net/lists/listinfo/plone-docs > > > ------------------------------------------------------------------------------ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
George L
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
Hi all,
Ah, I am more clearly seeing now how a developers manual and its sections/table of contents would work with this. I think originally I didn't see how it would work because (1) most documentation is scattered so that there are bits and pieces of what you need in different places, and (2) for reasons that make sense, a lot of documentation are like tutorials that walk you through step by step and sometimes roundabout rather than more matter-of-fact references. Are there plans for creating a developers manual? I see http://plone.org/documentation/manual/plone-2.5-user-manual and http://plone.org/documentation/manual/plone-developer-reference but when I search don't see anything ASAP on a developers manual. That could be a great learning tool for people wishing to see more real-life examples of different methods. Peace, community, justice, - George |
||||||||||||||
|
|
George L
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
Ah, I see a recent discussion now about moving things to manuals now that plone.org has been migrated. I also see some references to assessments of existing documentation. Can someone give a recap what the current work is and what manuals are being planned? Or give links to information like this? Peace, community, justice, - George |
||||||||||||||
|
|
Dylan Jay-4
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Markus Bleicher-4
I think people learn best from example. when the manual is there and
comprehensive then people will naturally refer to it more often. both in documentation and irc esp once they see other people doing so. Important thing is to help with the manual. What is it you need us to do Israel? On 05/01/2009, at 12:12 PM, Markus Bleicher wrote: > 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 >>> [hidden email] >>> https://lists.sourceforge.net/lists/listinfo/plone-docs >> >> >> ------------------------------------------------------------------------------ >> _______________________________________________ >> Plone-docs mailing list >> [hidden email] >> https://lists.sourceforge.net/lists/listinfo/plone-docs > > ------------------------------------------------------------------------------ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
On Mon, Jan 5, 2009 at 8:37 AM, Dylan Jay wrote:
First of all, thanks for volunteering. :-) I've already completed the assessment chart for the development section, indicating in the 2nd column wheter it should become part of a manual or not. I still have not clear at all what manuals will finally be in our documentation, e.g.:
-- israel ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by George L
On Sun, Jan 4, 2009 at 7:06 PM, George L wrote:
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 [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
|
Dylan Jay-4
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Israel Saeta Pérez
Hi Israel,
I had a look at your current list of development manuals. Perhaps I'm missing something here but is there a good reason not to make them chapters of one big manual? I can see lots benefits in one development manual and not many downsides but I must be missing something. On 06/01/2009, at 4:56 AM, Israel Saeta Pérez wrote: > On Mon, Jan 5, 2009 at 8:37 AM, Dylan Jay wrote: > Important thing is to help with the manual. What is it you need us to > do Israel? > > First of all, thanks for volunteering. :-) > > I've already completed the assessment chart for the development > section, indicating in the 2nd column wheter it should become part > of a manual or not. I still have not clear at all what manuals will > finally be in our documentation, e.g.: > • Content-types. > • Testing. > • Cataloging and searching (portal_catalog tool). > • Security. > • ... > I personally really need help in this task so feel free to step in > and help to write that list (use openplans). I reccommend looking at > the documentation of similar CMS's and frameworks to gather ideas. :-) > > -- israel > > ------------------------------------------------------------------------------ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
On Mon, Jan 5, 2009 at 11:39 PM, Dylan Jay wrote:
What benefits do you see in creating a mega-manual with several chapters instead of several manuals under the "development" topic? -- israel ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Dylan Jay-4
On Mon, Jan 5, 2009 at 11:39 PM, Dylan Jay <[hidden email]> wrote:
I had a look at your current list of development manuals. Btw, that list is only a premature draft and everybody's invited to participate to discuss and find the best set of manuals to explain all you need to know in order to install, use, deploy, customize and develop Plone. :-) -- israel ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
JoAnna Springsteen
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Israel Saeta Pérez
> What benefits do you see in creating a mega-manual with several chapters
> instead of several manuals under the "development" topic? > > fwiw, I prefer smaller manuals instead of one gigantic one. Think modular. Besides, I think a manual on Archetypes (for example) would be big enough on its own, without making it one large chapter in one even bigger manual. Ultimately though, it's Israel's call as he's the editor for this section. ------------------------------------------------------------------------------ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Israel Saeta Pérez
Hi Israel,
I realise a big manual is more work and harder to comprehend than keeping them small but I think its worth the extra effort. I'm sure it will all work in the wash and I'll have a go organising the documentation list you've compiled into some kind of chapter structure and see how it looks. We need a place to put the goals of plone code and where all the details fit in. We need to glue all the different bits of developer/ integrator documentation to make it make sense. The reason a bigger manual is better is to make that explanation of plone is as cohesive as possible. so any change is reviewed against the whole manual. don't you think its how all the pieces of plone fit togeather that we are missing? On 06/01/2009, at 10:17 AM, Israel Saeta Pérez wrote: > On Mon, Jan 5, 2009 at 11:39 PM, Dylan Jay wrote: > Hi Israel, > > I had a look at your current list of development manuals. Perhaps > I'm missing something here but is there a good reason not to make > them chapters of one big manual? I can see lots benefits in one > development manual and not many downsides but I must be missing > something. > > What benefits do you see in creating a mega-manual with several > chapters instead of several manuals under the "development" topic? > > -- israel > > ------------------------------------------------------------------------------ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ Check out the new SourceForge.net Marketplace. It is the best place to buy or sell services for just about anything Open Source. http://p.sf.net/sfu/Xq1LFB _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
JoAnna Springsteen
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
> I realise a big manual is more work and harder to comprehend than
> keeping them small but I think its worth the extra effort. > I'm sure it will all work in the wash and I'll have a go organising > the documentation list you've compiled into some kind of chapter > structure and see how it looks. Once again, this is Israel's call on how the section should be organized. While I'm sure he appreciates any and all input, it's ultimately up to him on how manuals and docs are organized within the section. > We need a place to put the goals of plone code and where all the > details fit in. The goals of the code is something that falls under the Framework team. It's not for the doc team to speculate on. We document functionality as it is. It's up to the developers to discuss goals of code/products and that discussion does not take place in these docs. We need to glue all the different bits of developer/ > integrator documentation to make it make sense. > The reason a bigger manual is better is to make that explanation of > plone is as cohesive as possible. so any change is reviewed against > the whole manual. Cohesive is good but just because a manual is big, does not make it cohesive or good. If you want a big manual, buy a book. Online documentation is meant to be modular and deliver what you need just in time. There is no reason a series of manuals can not be in a suggested order. But there is nothing here that you've mentioned that makes a case for why a large manual is better than a series of smaller ones. Ultimately, this is personal preference. I'm encouraging editors to go with the smaller manuals option because they are easier to maintain, easier to get volunteers to tackle smaller subjects, and less menacing looking to newbies when they are first learning a subject. > don't you think its how all the pieces of plone fit togeather that we > are missing? I don't disagree on this in principal, but I don't think having a huge manual is going to give us a full picture either. We do have some pretty good conceptual stuff in the end user manuals that give a good idea of how things fit together. ------------------------------------------------------------------------------ Check out the new SourceForge.net Marketplace. It is the best place to buy or sell services for just about anything Open Source. http://p.sf.net/sfu/Xq1LFB _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
Hello Dylan,
We're already collaborating with the Framework Team to try to document changes introduced by the accepted PLIPs in each version. Hopefully this will help us to keep official documentation a bit more up to date. :-) Regarding the big-manual thing, I think we should keep documentation as modular as possible because: - It makes easier to edit a page without worrying too much about breaking other parts of the documentation. - it allows readers to find and read only the pages they need to perform a certain task, without having to read the whole big-manual like if it were a book. But I'm open to contra-arguments. We reference some manuals from other ones when necessary, e.g. the GenericSetup manual from the Archetypes manual when explaining the GS bits, and avoid duplicating already existing information (hyperlinks are our friends), to keep the documentation as cohesive as possible. 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. -- israel ------------------------------------------------------------------------------ This SF.net email is sponsored by: SourcForge Community SourceForge wants to tell your story. http://p.sf.net/sfu/sf-spreadtheword _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs Israel Saeta Pérez
|
||||||||||||||
|
|
vedaw
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
I think having a handful of manuals makes it easier to solicit authoring
help on a given topic. And, many of these are already written, so why add more work by trying to combine them? If it makes sense to string them together in a given order, that can probably be accomplished, which sounds like the argument that was being posed... - Veda On 1/13/09 3:18 PM, "Israel Saeta Pérez" <[hidden email]> wrote: > Hello Dylan, > > We're already collaborating with the Framework Team to try to document > changes introduced by the accepted PLIPs in each version. Hopefully > this will help us to keep official documentation a bit more up to > date. :-) > > Regarding the big-manual thing, I think we should keep documentation > as modular as possible because: > - It makes easier to edit a page without worrying too much about > breaking other parts of the documentation. > - it allows readers to find and read only the pages they need to > perform a certain task, without having to read the whole big-manual > like if it were a book. > > But I'm open to contra-arguments. > > We reference some manuals from other ones when necessary, e.g. the > GenericSetup manual from the Archetypes manual when explaining the GS > bits, and avoid duplicating already existing information (hyperlinks > are our friends), to keep the documentation as cohesive as possible. > > 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. > > -- israel > > ------------------------------------------------------------------------------ > This SF.net email is sponsored by: > SourcForge Community > SourceForge wants to tell your story. > http://p.sf.net/sfu/sf-spreadtheword > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ This SF.net email is sponsored by: SourcForge Community SourceForge wants to tell your story. http://p.sf.net/sfu/sf-spreadtheword _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: Documenting Packages for Future Developers
|
|
||||||||||||
|
In reply to this post
by Israel Saeta Pérez
On 14/01/2009, at 10:18 AM, Israel Saeta Pérez wrote: > Hello Dylan, > > We're already collaborating with the Framework Team to try to document > changes introduced by the accepted PLIPs in each version. Hopefully > this will help us to keep official documentation a bit more up to > date. :-) awesome work. > > Regarding the big-manual thing, I think we should keep documentation > as modular as possible because: > - It makes easier to edit a page without worrying too much about > breaking other parts of the documentation. I'd say the opposite is true. By keeping it "modular" you increase the risk of breaking other parts by making giving conflicting advice in two different documents. Sure we shouldn't entagle the documentation is one part relies on the other but all I'm saying is that we somehow review documentation as a whole so it presents the least confusing view of plone at a code level as possible. NB Not talking about user level manual. Thats fantastic as it is, and is one big manual. > > - it allows readers to find and read only the pages they need to > perform a certain task, without having to read the whole big-manual > like if it were a book. I see no difference with indexing based on task whatever way we structure it. I'd just like to see us not avoid the hard problem of making plone code easy to understand to newbies. thats all. > But I'm open to contra-arguments. > > We reference some manuals from other ones when necessary, e.g. the > GenericSetup manual from the Archetypes manual when explaining the GS > bits, and avoid duplicating already existing information (hyperlinks > are our friends), to keep the documentation as cohesive as possible. > > 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. Totally disagree. Zope/Plone desperately needs to be explained from a code level how it all fits. Its a daunting task but should we avoid it just because its hard? Our learning curve is 6 months where it could be 2. Published books aren't the answer either as they go out of date too quickly and besides, aren't we open source? It also hurts our brand if we say you get the code for free but have to pay for documentation. Most importantly of all, developers are the laziest bunch of people on the planet, and possibly the cheapest. The most approachable platform is going to be popular and from an integrators point of view, we really need a lot more developers right now. Cutting down the documentation task into little chunks doesn't give us the place to explain how it all fits together. Without a place to explain, people who want to explain, like me and others, have no place to do so. Instead we get 50 explanations in blogs and tutorials spread all over the internet, all subtly different and the result is confusion. Perhaps now is not the time for the doc team to take this on board but at some stage I'd like to contribute to something that makes Plone easy to understand to a developer, beginning to end. Don't get me wrong. you guys are doing an awesome job. I'm just trying to be helpful. > -- israel > > ------------------------------------------------------------------------------ > This SF.net email is sponsored by: > SourcForge Community > SourceForge wants to tell your story. > http://p.sf.net/sfu/sf-spreadtheword > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------------ 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 _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
| Free Embeddable Forum Powered by Nabble | Help |
