From 0fd3dc03e564209b3b3bc0696cae9f04a2f77955 Mon Sep 17 00:00:00 2001 From: Ian Grigg Date: Mon, 25 Feb 2008 13:20:39 +0000 Subject: [PATCH] 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 --- DocumentsPolicy.html | 208 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 DocumentsPolicy.html diff --git a/DocumentsPolicy.html b/DocumentsPolicy.html new file mode 100644 index 0000000..61ac081 --- /dev/null +++ b/DocumentsPolicy.html @@ -0,0 +1,208 @@ + +COD 1 : Policy on Documents + + + + + + + +

Policy on Documents

+

Table of Contents

+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 --> + + \ No newline at end of file