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
This commit is contained in:
parent
94262a8fb9
commit
0fd3dc03e5
1 changed files with 208 additions and 0 deletions
208
DocumentsPolicy.html
Normal file
208
DocumentsPolicy.html
Normal file
|
@ -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>
|
||||
-> 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 (-> 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 "->". 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" (-> 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
|
||||
"<-- 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 COD 1 -->
|
||||
|
||||
</body></html>
|
Loading…
Reference in a new issue