This is an early work-in-progress Documents Policy by Sebastian. unknown date.

git-svn-id: http://svn.cacert.org/CAcert/Policies@596 14b1bab8-4ef6-0310-b690-991c95c89dfd
pull/1/head
Ian Grigg 16 years ago
parent 94262a8fb9
commit 0fd3dc03e5

@ -0,0 +1,208 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>COD 1 : Policy on Documents</title>
<meta name="author" content="Sebastian Kueppers">
<meta name="date" content="2007-04-07T00:01:18+0200">
<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>
<h1>Policy on Documents</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: COD 1-V1-DRAFT<br>
Status: Draft<br>
(C): 2007 Sebastian Kueppers
<h3>0.2. References</h3>
This document refers to: <br>
-&gt; RFC 2606 (required)<br>
-&gt; 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 (-&gt; COD 2) 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 "-&gt;". 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 "-&gt; 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
-&gt;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 -&gt;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" (-&gt; COD 2) 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
"&lt;-- END OF COD xx --&gt;". 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>
&lt;-- END OF COD 1 --&gt;
</body></html>
Loading…
Cancel
Save