DocumentationComments

Here is a list of further documentation that we will need at some point:

• OverviewDocumentation?

  Overview documentation is what I would consider Marketing material. This includes magazine articles, fact sheets, FAQs? and so on. This documentation should be directed at decision makers (see ZopeEvaluator). This documentation is absolutely crucial, if Zope wants to grow 10x.

  It may be a bit early for this type of documentation, but I think a bit more press coverage would not hurt at this point.

  Here are some possible tasks:

  • Update the Zope 3 FAQ.
  • Write an article about the Component Architecture.
  • Write a document comparing Zope 2 and 3, pointing out differences and similarities.
• UserDocumentation?

  User Documentation should concentrate on addressing SiteDevelopers, InformationArchitects and SiteManagers. This documentation should be very narrative, so that it gives a nice and light entry for newcomers.

  This aspect of the documentation is perfect for writing science fiction, something Jim wants to happen much more. On the other hand some concrete tasks could be documented already, for example on how to register the PostgreSQLDA?, so it can be used.

  I therefore propose that someone should start writing a UserCookbook? or similar. Note: I noticed that writing recipe-like pieces of documentation is much easier than long book chapters. It also requires knowledge in particular areas.

  • ZopeX3DifferencesOnWindows - This document covers some of the differences between installing and configuring Zope X3 compared to Zope 2.x on the Windows platform.

  Further tasks:

  • Write a document (article or book) on how to implement a simple Web Site or application (for example a bug tracker).
  • Write small How-tos.
  • Write Zope 2 to 3 transition documents (SiteDeveloper level).
• ReferenceDocumentation
  • APIDocTool

    The API documentation tool allows you to browse through all registered interfaces, components, and ZCML directives. It concentrates on providing all information possible while not overwhelming the reader with too much text. It also tries to create links to other sections of the documentation whenever possible. The API documentation is generated dynamically, which means that it is always customized to your systems configurations.

  • OnlineHelp?

    Stephan has implemented a very basic Online Help that supports text and HTML files for content. Thus the OnlineHelp? proposal has been implemented. The online help now supports also structured text and resources, i.e. images. One of the Online Help pages also describes how to register pages for it and links to other online documentation, such as the API doc tool.

  Tasks:

  • It would be nice to include the glossary in the Online Help.