This document describes the process for creating new official Zope
documentation.
Zope documentation projects will be run in the fishbowl. This means
that they are developed in an open way with community input. Most of
the documentation process is driven by the manager The manager
initiates the documentation project and is in charge of keeping the
project and its contributors on track.
Here are the steps you should take as a manager to initiate a new
documentation project.
Identify Audience and Audience Need
Before embarking on a new documentation project, it is important
to make sure that there is a unmet need that the new project will
address.
Zope has three general audiences:
Users
Users use the Zope application through the management interface.
The primary sources of documentation for this audience are:
Zope Book, Tutorial, Online Help System, User oriented How-Tos.
Developers
Developers extend Zope with Products, or maintain or extend
the Zope core. This encompasses not only community members
and users, but also Digital Creations' employees. The primary
sources of documentation for this audience are: Developer's
Guide, Developer API Project, Developer oriented How-Tos.
Administrators
Administrators install, maintain, or upgrade one or more Zope
systems. The primary sources of documentation for this audience
are: Administrator's Guide, Administration oriented How-Tos.
Write Zope documentation to approach one of these three audiences.
When extending or working on an existing documentation artifact,
make sure your effort does not cross over into another audience's
domain. For example, if writing a chapter on XML for the Zope
Book, do not discuss implementation details like how XML elements
work with the persistent database. This information is not
oriented toward the User audience, it is oriented toward the
Developer audience and should go into a corollary, advanced
section in the Developer's Guide.
Make sure to ask yourself whether the unmet need would better be
addressed by bolstering an existing documentation project rather
than starting a new one.
Now that you've identified the audiance, their unmet need, and
have verified that no existing documentation project should be
improved to meet the need go to the next step.
Determine Topic and Scope
Determine the topic and scope of your project before you write it.
Documentation projects cover one central theme which is the
topic. The scope of your documentation is the depth of detail
given to your topic.
Make sure that your topic and scope fit with your audience and
unmet need. Double check that your documentation might not work
better as a part of an documentation project. For example, might
your topic work well as a chapter in the Zope Book or in the
Developer's Guide?
Survey Related Documentation
Before you embark on creating a new piece of documentation you
should survey the existing documentation, both official and
unofficial. If there is already a piece of official document that
has roughly the same topic and scope, then it probably isn't a
good idea to create a new artifact. It's easier for readers and
maintainers to have one doc instead of two.
Once you determine that your project isn't redundant, then you
should survey existing material with an eye to incorporating as
much of it as possible into your project. The more content you can
harvest from existing writing, the better. You may be able to not
only save yourself from writing, but you may gain collaborators if
you can get the support of How-To authors and others who have
written material that is related to your project.
Create an Outline
An outline is a hierarchical breakdown of a topic that describes
the structure of the artifact. Outlines are the most important
organizational tool for all actors involved in documentation.
Authors use an outline to guide the content as it is written.
Editors use an outline to evaluate the topic, scope, quality, and
progress of an artifact. Maintainers use an outline to fit
revised material smoothly into an existing artifact, and,
ultimately, Readers use an outline to navigate through
documentation.
An outline consists of a sequence of top-level, key ideas that
encompass the scope of your topic. Each top-level key idea should
be broken down into a second level of more specific details of
each key idea. In necessary, an outline can descend through as
many levels of detail as are needed to describe the topic. Be
advised, however, excessive depth of an outline for most
documentation artifacts is a sign of a topic that may need to be
re-factored into multiple topics.
An outline is best developed with the contributions of all
documentation actors. Authors contribute topics they feel they
can describe well, Editors contribute revision and scope
management to an outline, and Readers drive the scope of an
outline by their needs. Although these patterns need not be
followed exactly, the most important stage of communication
between all the actors is during the development of the
outline.
If the Authors and Editors are not yet chosen while developing the
outline you may wish to revisit the outline once you have decided
upon Authors and Editors.
Create a Documentation Project
Now you have enough information to create a fishbowl documentation
project. Contact [email protected] and we'll
help you set up a new documentation project.
From here on out you should actively maintain the project by
checking for comments from Reviewers. The project is the chief
form of communication between you the manager and other folks who
will get involved in the project.
Determine Authors and Editors
After an outline is created, identify Authors and Editors. An
Author's role is to create raw content for each heading in an
outline, and to revise existing content. An Editor's role is to
take an outside perspective on that content and to verify its
scope, completeness, style, and to a certain extent its
correctness. Often, the roles of Author and Editor are interposed
on the same person, for example, Amos and I both worked as
Authors, and then as Editors to review each others work on the
O'Reilly book. This saved a lot of effort for the O'Reilly editor
also and reduced her burden as the editorial bottleneck.
Authors and Editors may both be drawn from the ranks of Reviewers
who have contributed to the development of the project so
far. Authors and editors may be DC employees or may be community
members. Also, Authors and Editors may join and leave the project.
Decide Authoring Procedures
The procedure chosen for authoring content depends on the project,
the participants, and resource constraints. All procedures,
however, are based on the same concept, iteration. One rough
cut at a document is not a complete document. A document must go
through several revisions before it can be considered complete and
correct. This must be stressed strongly: a document that has gone
through only one iteration is not complete, and an Author should
always assume that raw material contains technical and language
errors, needless words, and requires at least one iteration of
editorial revision before it can be considered completed.
The most simple procedure involves one Author and one Editor. The
author creates content that is sent to the Editor. The Editor
makes corrections and comments and sends them back to the Author.
The process repeats until the Author and Editor agree that the
work is complete. If you have more than one Author and Editor,
you the Manager should work out a system for assigning writing and
editing work to all participants. Generally Authors will be
assigned sections from the outline to work on and Editors will be
assigned to review work by Authors.
Authors and Editors may periodically choose to make a snapshot of
their work available in the fishbowl. In this case reviewers can
make comments in the fishbowl. The author or editor who posted the
rough draft is responsible for responding to the comments and
working them into their next draft.
Each documentation project includes a tracker which can be used
by the manager, author(s) and editor(s) to collaborate.
For information on authoring formats see Documentation Authoring
Formats.
For information on where to save documentation see Documentation
CVS Repositories
At this point your documentation project is ready to roll. As the
manager you job is to make sure that Authors and Editors are
productive and happy and to respond to Reviewer comments in the tracker.
You may need to recruit new Authors and Editors if/when your current ones
leave the project.
Log in
Forgot your password?