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
-- 
View this message in context: http://n2.nabble.com/Documenting-Packages-for-Future-Developers-tp2107425p2107425.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