Introduction

This document explains how to write and maintain official Zope documentation. It tells you how everything you need to know to contribute to official Zope documentation. If you have a question that this guide does not address please send mail to [email protected]

What is Official Zope Documentation?

Official Zope documentation is Zope documentation that is produced and maintained using the official documentation process. The process is designed to keep official documentation up to date and error free. Official documentation is written and maintained by many folks inside and outside of Digital Creations. There are lots of other types of useful Zope documentation such as Zope.org how-tos which do not follow the documentation process.

You can find a list of official Zope documentation on the main Official Documentation Projects page. Each documentation project includes information about who's working on it, its status, and how to contribute.

How an Official Documentation Project Works

Every official documentation project has a number of people who work on it:

Manager - The person who oversees the project and makes sure that the project is progessing successfully. The manager is reponsible for maintenance and publishing the documentation. You don't need to be a Digital Creations employee to manage an official documentation project.

Author(s) - The person or people who write the documentation. You don't need to be a skilled writer to be a documentation author.

Editor(s) - The person or people who edit the documentation for style, content, and correctness. You don't need to be a skilled editor to be a documentation editor.

Each documentation project has a web page that lists the participants, and gives information about the project including its status. From the project page you should be able to offer comments on the project and sign up to work on it. You can also access the project's Tracker. The tracker contains comments, bug reports, and suggestions from readers and participants.

Helping Out with Existing Zope Documentation

You can help out on an existing official documentation project in many ways.

Read Documentation and Give Feedback

Read official documentation on Zope.org if you have a question or comment submit it in the web form on the bottom of every page. If you are reading documentation that doesn't accommodate a feedback form (for example a PDF file, or an online help file) send email to the feedback address at the bottom of the page. Your comments will be entered into a feedback database, and you should hear back from the documentation's manager.

Review Documentation Projects

Check out the official documentation projects and find a project that interests you. You can see the project's status and examine drafts of forthcoming documentation. You can leave your comments for authors and editors.

Take a Role in a Documentation Project

If you are particularly interested in a documentation project, write to the manager of the project and sign up as an editor and/or author. You don't have to be an experienced writer to make a difference. Every documentation project should include contact information for the manager.

Where to Go From Here

For Documentation Managers

• Developing New Official Documentation - This process is somewhat lengthy in comparison to working on an existing documentation project. In general there shouldn't be a lot of need to create new official documentation projects. If there is, it may be that existing documentation projects need to be improved.

• Maintaining Official Documentation - This document discusses how to keep documentation up to date. It covers handling changes in Zope and suggestions by readers.

• Delivering Official Documentation - This document explains how to publish documentation. It describes how to build documentation from sources and distribute it via Zope.org.

For Developers

• Documenting Your Changes to Zope - When you change Zope, you potentially affect many pieces of official documentation. Follow the steps listed in this document to ensure that your changes are incorporated into Zope documentation.

• Documenting Your Zope Product - Documentation for your Zope product is not considered official Zope documentation. However, it is important. Eventually this information will be moved to the Zope Developer's Guide.

For Documentation Writers

• Writing Official Documentation - This document explains how to write official documentation. It explains the process of working with the manager and editor. It also gives you writing tips.

For Documentation Editors

• Editing Official Documentation - This document explains how to edit official documentation. It explains the process of working with the manager and author. It also gives you writing tips.