32b9588463
COD number is now 3. Name should have Policy at end. git-svn-id: http://svn.cacert.org/CAcert/Policies@610 14b1bab8-4ef6-0310-b690-991c95c89dfd
210 lines
9.8 KiB
HTML
210 lines
9.8 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head><title>COD3 : CAcert Official Documents Policy</title>
|
|
<meta name="author" content="Sebastian Kueppers">
|
|
<meta name="date" content="2008-02-25">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8">
|
|
</head><body>
|
|
|
|
<center><big><b>W o r k -- i n -- P r o g r e s s</b></big></center>
|
|
|
|
<h1>CAcert Official Documents Policy</h1>
|
|
<h2>Table of Contents</h2>
|
|
0. General<br>
|
|
0.1. Document Information<br>
|
|
0.2. References<br>
|
|
1. Introduction<br>
|
|
1.1. Background on COD document series<br>
|
|
1.2. How does the documentation work?<br>
|
|
2. General COD editorial policies<br>
|
|
2.1. Immutability<br>
|
|
2.2. Publication language<br>
|
|
2.3. Publication format<br>
|
|
2.4. Consistent Document Style<br>
|
|
2.5. Assignment of COD Numbers<br>
|
|
2.6. References and citations<br>
|
|
2.7. URLs in documents<br>
|
|
2.8. Abbreviations<br>
|
|
2.9. Requirement-level words<br>
|
|
2.10. Translating CODs<br>
|
|
3. Sections in a COD<br>
|
|
3.1. Title<br>
|
|
3.2. Table of contents<br>
|
|
3.3. "General"-section<br>
|
|
3.4. Body section<br>
|
|
3.5. Citation sources<br>
|
|
3.6. Appendices<br>
|
|
3.7. End-of-document and author's (email) address<br>
|
|
4. EOD-section<br>
|
|
|
|
<h2>0. General</h2>
|
|
<h3>0.1. Document Information</h3>
|
|
Document-ID: COD3<br>
|
|
Status: wip V0.2<br>
|
|
(C): 2007 Sebastian Kueppers
|
|
|
|
<h3>0.2. References</h3>
|
|
This document refers to: <br>
|
|
-> RFC 2606 (required)<br>
|
|
-> RFC 2119 (required)<br>
|
|
|
|
<h2>1. Introduction</h2>
|
|
This document provides information for authors of CAcert Official Documents (COD).<br>
|
|
"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.<br>
|
|
Policies and other documents that are covered by the Configuration
|
|
Control Specification (-> COD2) contain a corresponding note in
|
|
their "general" section (see below).<br>
|
|
It summarizes COD editorial policies and formatting requirements,
|
|
answers frequently asked questions, and serves as a model for
|
|
constructing a properly formatted COD.
|
|
<h3>1.1. Background on COD document series</h3>
|
|
The CAcert official documents series, short COD, form an archive of documents issued officially by CAcert, Inc.<br>
|
|
|
|
<h3>1.2. How does the documentation work?</h3>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.<br>
|
|
A document starts in WIP-status (Work In Progess). When it is finished, it will be published on the homepage in DRAFT-mode.<br>
|
|
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.<br>
|
|
After a while in draft-status without revision the document will be given "approved" status.<br>
|
|
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.<br>
|
|
|
|
<h2>2. General COD editorial policies</h2>
|
|
|
|
<h3>2.1. Immutability</h3>
|
|
Since CODs form an archival series they cannot be altered.<br>
|
|
If changes to an approved document are required it has to be filed as a new version and run through the approval process again.<br>
|
|
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.
|
|
<h3>2.2. Publication language</h3>
|
|
Official language for CODs is English, in cases of doubt it is en_AU (Australian English).<br>
|
|
Translations are welcome, but will only serv to inform the reader and will not habe any legally binding quality.
|
|
|
|
<h3>2.2. Publication format</h3>
|
|
CODs are published as HTML files.<br>
|
|
CODs should use HTML-code as simple as possible.<br>Other
|
|
file formats may be used if approved of by the Documentation Officer
|
|
(e.g. for graphical content or officially issued presentations).<br>
|
|
If file formats other than HTML are used free and interchangeable formats will be preferred.
|
|
|
|
<h3>2.4. Consistent Document Style</h3>
|
|
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.
|
|
<h3>2.5. Assignment of COD Numbers</h3>
|
|
COD-numbers are not assigned until late draft status and are assigned by the Documentation Officer.<br>
|
|
|
|
<h3>2.6. References and citations</h3>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)".<br>
|
|
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.<br>
|
|
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).<br>
|
|
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.
|
|
<h3>2.7. URLs in documents</h3>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.<br>
|
|
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.<br>
|
|
|
|
<h3>2.8. Abbreviations</h3>
|
|
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.
|
|
<h3>2.9. Requirement-level words</h3>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.
|
|
<h3>2.10. Translating CODs</h3>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.
|
|
<h2>3. Sections in a COD</h2>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.<br>
|
|
<br>
|
|
I. Title (required)<br>
|
|
II. Table of contents (required)<br>
|
|
III. "General"-section (containing document information and references, required)<br>
|
|
IV. Body section (required)<br>
|
|
V. Citation sources<br>
|
|
VI. Appendixes<br>
|
|
VII. End-of-document and Author's (email) address (required)<br>
|
|
<br>
|
|
<h3>3.1. Title</h3>
|
|
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.
|
|
<h3>3.2. Table of contents</h3>
|
|
A table of contents (TOC) section shall provide a quick overview of the different sections in a COD.<br>
|
|
It can be left out in very small CODs, in cases of doubt the Docmentation Officer will decide.
|
|
|
|
<h3>3.3. "General"-section</h3>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".<br>
|
|
If a COD is a policy of CAcert Inc and/or controlled by the
|
|
"Configuration Control SpecificationConfiguration Control
|
|
Specification" (-> COD2) this fact is stated in this section, too.
|
|
<h3>3.4. Body section</h3>
|
|
The general section is followed by the document body.<br>Each
|
|
COD should have an introduction that explains the motivation for the
|
|
COD and (if appropriate) describes the applicability of the document.<br>
|
|
|
|
<h3>3.5. Citation sources</h3>
|
|
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.
|
|
<h3>3.6. Appendices</h3>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").
|
|
<h3>3.7. End-of-document and Author's (email) address</h3>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.<br>
|
|
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.
|
|
<h3>4. EOD-section</h3>
|
|
|
|
Author: Sebastian Kueppers, cacert@kueppers.ath.cx<br>
|
|
<br>
|
|
<-- END OF COD3 -->
|
|
|
|
</body></html>
|