Policy on Documents

0. General
0.1. Document Information
0.2. References
1. Introduction
1.1. Background on COD document series
1.2. How does the documentation work?
2. General COD editorial policies
2.1. Immutability
2.2. Publication language
2.3. Publication format
2.4. Consistent Document Style
2.5. Assignment of COD Numbers
2.6. References and citations
2.7. URLs in documents
2.8. Abbreviations
2.9. Requirement-level words
2.10. Translating CODs
3. Sections in a COD
3.1. Title
3.2. Table of contents
3.3. "General"-section
3.4. Body section
3.5. Citation sources
3.6. Appendices
3.7. End-of-document and author's (email) address
4. EOD-section

0. General

0.1. Document Information

Document-ID: COD 1-V1-DRAFT
Status: Draft
(C): 2007 Sebastian Kueppers

0.2. References

This document refers to:
-> RFC 2606 (required)
-> RFC 2119 (required)

1. Introduction

This document provides information for authors of CAcert Official Documents (COD).
"Official" documents are all documents issued by CAcert Inc. that shall be supervised and versionized for legal (e.g. policies) or handy (e.g. the document how to organize events) reasons.
Policies and other documents that are covered by the Configuration Control Specification (-> COD 2) contain a corresponding note in their "general" section (see below).
It summarizes COD editorial policies and formatting requirements, answers frequently asked questions, and serves as a model for constructing a properly formatted COD.

1.1. Background on COD document series

The CAcert official documents series, short COD, form an archive of documents issued officially by CAcert, Inc.

1.2. How does the documentation work?

The documentation process and the need for officially issued documents can be initiated by CAcert Inc. (by stating the need for an official document on a special subject) or by individuals.
A document starts in WIP-status (Work In Progess). When it is finished, it will be published on the homepage in DRAFT-mode.
Draft documents are assigned to a COD-ID by the documentation officer and will be published on the website/SVN. While it is a draft document everybody is asked to revise the document and send comments, errors and additions to the author.
After a while in draft-status without revision the document will be given "approved" status.
When a document has reached "approved" status, changes will not be accepted any more. All changes and additions have to be filed as new versions in draft-status. This new version will stay in draft-status for revision as stated above. When a new version of a document finally reaches "approved" status the older version will be marked as obsolete and the new version will officially be published by the documentation officer.

2. General COD editorial policies

2.1. Immutability

Since CODs form an archival series they cannot be altered.
If changes to an approved document are required it has to be filed as a new version and run through the approval process again.
If a new version of an existing COD is approved it will keep its COD-number but will be given a new Version-ID by the Documetation Officer.

2.2. Publication language

Official language for CODs is English, in cases of doubt it is en_AU (Australian English).
Translations are welcome, but will only serv to inform the reader and will not habe any legally binding quality.

2.2. Publication format

CODs are published as HTML files.
CODs should use HTML-code as simple as possible.
Other file formats may be used if approved of by the Documentation Officer (e.g. for graphical content or officially issued presentations).
If file formats other than HTML are used free and interchangeable formats will be preferred.

2.4. Consistent Document Style

The Documentation Officer attempts to enforce a consistent style of CODs. To do this, the Documentation Officer may choose to reformat a submitted COD or ask the author to reformat it. This effort can be minimized if the submitted document matches the style of the most recent CODs.

2.5. Assignment of COD Numbers

COD-numbers are not assigned until late draft status and are assigned by the Documentation Officer.

2.6. References and citations

If a COD refers to another COD or external document these documents must be named in section 0.2. of the specific COD. In text references to external documents they shall be marked with "->". If the named document is essential for understanding and using the COD the tag "(required)" shall be added. References for information only will have no tag or the tag "(informational)".
Citation sources shall be numbered sequentially in square brackets (e.g. "[1]"). A comprehensive list of citation sources should then be given in an appendix.
References within the same COD-document can be noted as "-> COD x (this document)". Even if the document is an HTML-file the use of (internal) links is not allowed (since links will not work if the document is e.g. printed).
If a COD requires any other document (another COD or an external document) it can not be given approved status until any required document is given "approved" status.

2.7. URLs in documents

Since URLs are no stable reference they should not be used in CODs. Exceptions may be made for references in those cases where the URL is the most stable reference available.
DNS names given to examples should make use of the examples defined in ->RFC 2606 ("Reserved Top-Level DNS Names") to avoid conflicts with existing domains.

2.8. Abbreviations

Abbreviations should be written out when used for the first time, except for common abbreviations which everybody will easily recognize. The Documentation Officer will make the final judgement weighing obscurity against complexity.

2.9. Requirement-level words

Some documents contain certain capitalized words ("MUST", "SHOULD", etc.) to specify precise requirements for technical points. In CODs these words are interpreted according to ->RFC2119. If other capitalized words are used the correct interpretation must be specified in the document. Abusive use of required-level words must be avoided. The words are intended to provide guidance to implementors about specific technical features or legal affairs.

2.10. Translating CODs

The translation of CODs into another language is permitted. However, the original author and/or the Documentaton Officer should be informed of such translations. Translations will be listed on the documentation homepage. Translated versions are for informational use only, see section 2.2. of this docment.

3. Sections in a COD

A published COD should contain the sections in the following list. Some of these sections are compulsory, as noted. The shown order is required if no good reasons are given as to why the order should be different.

I. Title (required)
II. Table of contents (required)
III. "General"-section (containing document information and references, required)
IV. Body section (required)
V. Citation sources
VI. Appendixes
VII. End-of-document and Author's (email) address (required)

3.1. Title

Choosing a good title can be a challenge. A good title should represent the scope and purpose of the document without being either too general or too specific.

3.2. Table of contents

A table of contents (TOC) section shall provide a quick overview of the different sections in a COD.
It can be left out in very small CODs, in cases of doubt the Docmentation Officer will decide.

3.3. "General"-section

The "general" section contains the general document information (COD-ID, status, copyright) and the list of references. If a table of contents is available this section is usually lablled as section "0".
If a COD is a policy of CAcert Inc and/or controlled by the "Configuration Control SpecificationConfiguration Control Specification" (-> COD 2) this fact is stated in this section, too.

3.4. Body section

The general section is followed by the document body.
Each COD should have an introduction that explains the motivation for the COD and (if appropriate) describes the applicability of the document.

3.5. Citation sources

If citations are used in the document the specific citation sources should be listed here. There is no specific format required since citation sources can vary.

3.6. Appendices

The appendix-section can be used e. g. for detailed information on technical focuses. Usually appendices are numbered from "A"..."Z" (e.g. "Appendix A") and can be sub-sectioned ("A.1", "A.2").

3.7. End-of-document and Author's (email) address

The last section of any COD-document should contain the author's email-address (so that comments and additions can be addressed directly to the author). If no author is known or if he is otherwise unavailable this will be the Documentation Officer's address.
The very last item of any document is the end-of-document-note coded as "<-- END OF COD xx -->". All text below this note does not belong to the document any more.

4. EOD-section

Author: Sebastian Kueppers, cacert@kueppers.ath.cx

<-- END OF COD 1 -->