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" <[email protected]> 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
[email protected]
https://lists.sourceforge.net/lists/list
> info/plone-docs



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