DocumentationProcess

Documentation Process

This is the Digital Creations process for creating documentation.

1. Identify Audience.

   Zope has three, top-level 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
     • Interfaces Wiki (or its successor)
     • Debugging information (may be subsumed into DevGuide?)
     • 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 tag 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.

2. Determine topic and scope.

   Documentation artifacts are sub-components of a larger outline. Determine the topic and scope of the artifact and where it fits into an existing document's outline before you write it.

   Documentation artifacts cover one central theme which is the topic. Topics of these artifacts are determined from the outline of an existing documentation artifact, like the Zope Book, the Developer's Guide, or the Administrator's Guide. For example, the Developer's Guide may have a large, broad outline that covers all development topics. The topic of a specific documentation artifact, like "Security Assertisions" comes from a heading in this broader outline, and will "explode" the topic into a more granular outline.

   The scope of your documentation is the depth of detail given to your topic. The scope of your topic should not be overly broad; an artifact that documents one topic should not try to document another topic that is elsewhere in the outline of the artifact you are expanding.

   Be aware that the broader outline is not perfect, and that new topics may be discovered in the course of documenting an existing topic. These topics should be considered for inclusion in the broader outline as a topic in their own right, and should go through their own documentation process.

3. 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 refactored 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.

4. 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 editors 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.

5. 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.

   There are two example models you can use to develop an authoring procedure, but you may come up with one on your own. The first model involves only 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.

   The second model was used by Amos and me to write the O'Reilly Zope Book and involves more than one Author or Editor. In this model, two Authors each collaborate on the outline, revising and rewriting it until it is satisfactory. Then each author choose a section of the outline to write a rough draft. After completing a rough draft each Author then switches roles to Editor and reviews the other Author's work. At discreet milestone goals the currently completed work is sent to a third Editor to review large chunks of content. By the time the content gets to the third editor, it has been through several iterations of writing and revision by the Authors.

6. Maintainers.

   As software that is described by documentation changes, maintainers must change the documentation to remain up-to-date and accurate. The role of the Maintainer is important and should not be neglected. When budgeting resources for documentation, take into account the need for keeping to documentation up to date with respect to the software.

7. Maintenance procedures.

   XXX

8. Feedback procedures.

   Without soliciting feedback from the documentation's intended audience the Authors and Editors have no way of knowing if the information is relevant, correct, comprehensible or applicable to the audience's needs. Therefore, it is important for Authors and Editors to provide a feedback mechanism during the authoring process, and for a feedback mechanism to be available after the "final draft" so that maintainers have an idea of what needs to be done. A feedback mechanism like this is also useful for the authors and other internal actors to use, much like DC employees use the collector to keep track of bugs and ideas that come to them in the course of an unrelated project.