Documentation is one of Zope's weakest points. For Zope to be a popular application server and a vital open source project this needs to change.

Our goal is to facilitate the acquiring and sharing of knowledge about Zope.

• It should be easy to learn how to make Zope do what you want. This includes: Installing and maintaining Zope, building basic sites, doing more advanced work with DTML, Python, and External Methods, and extending Zope with ZClasses and Python Products.
• It should be easy and rewarding for DC folks and the Zope community to contribute to and maintain documentation.

Zope documentation needs effectively address the educational needs of the Zope community. This includes a wide range of audiences with a wide range of needs.

Zope documentation is used, authored, and maintained by a wide range of people.

Prospective Zope users & developers

These people need to be able to find out about Zope. They need to be able to understand what Zope can do for them and be able to evaluate whether Zope is a good fit for their needs.

Zope users

Zope users need to be able to architect and maintain basic Zope sites. They need to understand basic Zope objects and the management framework. Tutorials, examples, and online help are especially important for these folks. To the extent that Zope users delve into DTML, Python and External Methods, they need to be able to consult the Zope API.

Zope developers

Developers need to be able to learn how to extend Zope with ZClasses and Python Products. They need to be able to understand the API and conventions of the Zope framework. They also need tools and procedures to document their extensions.

Zope hackers

Zope hackers need to be able to understand Zope internals enough to make changes to the core. These folks also need tools and processes to communicate their knowledge of the Zope core to others in the form of API and other documentation.

Zope administrators

Administrators need to know how to install and maintain Zope. They need to be able to assess and control Zope performance and Zope's interactions with the machines it runs on.

ZDP

The ZDP and other folks need tools and processes to contribute to all forms of Zope documentation. Documentation contributors should not need to use proprietary systems to contribute. Folks who are interested should be able to have ownership and control of certain pieces of official documentation. It should also be easy for people to contribute in other important ways by reviewing, offering corrections, and offering examples.

Additionally it must be easy and rewarding for folks at DC and within the Zope community to author and maintain documentation. It should be easy for people of different technical and writing abilities to contribute in effective ways. The Zope community and especially the ZDP have great energy and ideas that we cannot continue to ignore.

The DC Portland office is responsible for Zope Documentation. This means that we will drive the process forward by developing documentation projects, measuring documentation success and balancing the concerns of different constituencies. We cannot do all the work ourselves, but we can direct the work and provide support for folks who want to help.

The ZDP has contributed energy, tools, and ideas for Zope documentation. We need to learn from the ZDP and use their solutions where appropriate. We need to make sure that all projects that we propose take the ZDP into account.

Goals

As part of improving Zope documentation we need to have better ways of assessing the state of documentation. We need to be able to tell what areas most need work, and we need to be able to tell if we are effective in improving the situation.

To this end we will develop some ways of assessing documentation. These could include developing a catalog of existing documentation, measuring documentation downloads/page views, conducting surveys, measuring documentation growth, measuring community contributions, consulting the ZDP, and monitoring community complaints.

Constituencies

Here are some specific projects to improve Zope documentation that are now underway.

Online Help System

There is currently an online help system implementation in CVS. It will appear in Zope 2.2. The help system is designed to provide context-sensitive help for Zope users. Zope developers can use the system to provide help for their ZClass and Python Products.

The help system can be expanded later to provide API and tutorial documentation.

The content for basic Zope object help is written in DocBook XML and will be available via CVS so that community members can easily submit patches to the help content for basic Zope objects.

Project Contact: [email protected]

Zope Interfaces

Currently we are incepting a project to provide API documentation for the Zope core and basic Zope objects. This facility will also be available to Zope developers to provide API documentation for their Zope Products.

Zope interfaces should provide API documentation to Zope users who are using DTML, Python and External Methods. Interfaces will also be helpful for Zope developers to guide their use of the Zope framework.

Project Contact: [email protected]

Overhaul Zope Guides & References

The current Guides and References need to be updated to keep pace with Zope development. They also need to be opened up so that community members and everyone at DC can contribute to them. To this end we are transitioning away from Framemaker towards DocBook XML. We will make documentation available via CVS and provide write access to selected community members. This will make it easier for folks to make changes and additions to Zope's core documentation. We will provide examples to show how to author Guide and Reference material, and we will maintain scripts to build output in a variety of formats.

We are also considering a system of modularizing examples. Perhaps examples could be authored separately and then categorized in such a way as to allow them to be bound to Guides and References. The ZDP Snippets project is a good model to look at.

Project Contact: [email protected]

Responsibility

After we have a better assessment of the current state of Zope documentation we will propose additional projects to meet the most dire needs. Here is a sampling of possible simple projects.

Searchable Mailing List Archive

Tremendous amounts of information goes by on the Zope mailing lists. Providing a way of searching the mailing lists would go a long way towards capturing and reusing that information.

Better Zope.org Documentation Organization

Tips and How-Tos could be organized in a better fashion, perhaps using Topics. How-Tos could also include a way for readers to review and contribute to How-Tos.

Metrics

Current Projects

Possible Future Projects