[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: SSTC document guidelines
Bob & I collaborated on modifying the document guidelines doc he posted last
week. Present OASIS-specific version is below. Comments encouraged.
thanks,
JeffH
-----
OASIS Security Services Technical Committee Document Guidelines
draft-sstc-doc-guidelines-00.txt
RL "Bob" Morgan
Jeff Hodges
January 30, 2001
comments to: security-services@lists.oasis-open.org
This document is an OASIS-Draft and is in conformance with
relevant OASIS SSTC document standards (i.e., itself).
Abstract
This document specifies document-handling practices for the OASIS
Security Services Technical Committee (SSTC) and its subcommittees.
1. Introduction
This document recommends standards for name, format, and availability
of documents that are being worked on in subcommittees of the
OASIS SSTC (and, potentially, other areas of OASIS).
It is loosely based on standards for documents in IETF
working groups, as described in [1] and [2]. The intended benefits
are: clarity of document status, uniform availability, consistent
document-handling among different working groups, and facilitation of
group web site maintenance; all while being as consistent as possible
with the otherwise free-form OASIS process.
The standards expressed here are for draft documents produced
specifically for use in the SSTC and its subcommittees.
See [5] for the standards used for producing OASIS Committee
Specifications, OASIS Specifications and other OASIS-wide
documents.
2. Conventions used in this document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [0].
"TC" is used throughout this document to mean "Technical Committee",
which specifically means the Security Services TC at this stage in
this document's life cycle.
3. Intellectual property rights policies
The OASIS General Policy for intellectual property rights (IPR) is
expressed in [6] as:
In all matters of intellectual property rights and procedures,
the intention is to benefit the public at large, while respecting
the legitimate rights of others.
The reader must refer to [6] for detailed description of IPR rules,
conventions, and required document noticies. TC and TC
subcommittee draft documents SHOULD contain applicable IPR notices
from [6], and approved TC final documents MUST contain applicable
notices from [6].
4. Document evolution model
This recommendation provides a simple model of how documents move from
initial ideas to final, approved SSTC work products.
Documents begin as drafts, proceed through a number of revisions, and
finally, upon approval by the committee, are published as Committee
Specifications. Upon approval by the OASIS membership as a whole, they
are published as OASIS Specifications. [5] documents the latter two
steps of this overall process. This document is concerned with the
steps prior to a document becoming a Committee Specification.
Document filenames reflect the overall process. Draft documents are
denoted by their filenames beginning with "draft-". Draft documents
are not permanent, and may be superseded or removed at any time.
Completed TC documents that are intended to be submitted for OASIS
membership approval should be published as Committee Specifications
according to the OASIS rules and conventions documented in [5].
Filename conventions for Committee Specifications and OASIS
Specifications are given in [5].
A distinction is made between "individual submission" draft documents
and "TC or TC subcommittee" draft documents (hereinafter referred to
simply as "TC draft documents"). An individual submission
(which may of course be submitted by more than one person) represents
only the opinions of its authors. A TC draft document is intended
to reflect the (rough) consensus of the TC or applicable TC
subcommittee. The topics of TC draft documents will typically be
specified in the TC or subcommittee charter or are otherwise agreed
upon by the TC, while individual submissions may be on any topic
relevant to the work.
Document filenames reflect the distinction between individual
submissions and TC or subcommittee documents.
Migration of individual submission draft documents to TC draft
documents is done by (rough) consensus of the TC or subcommittee.
A working group document may migrate to an individual submission
by (rough) consensus of the TC or subcommittee.
5. Document guidelines
These guidelines apply to all documents submitted for committee or
subcommittee consideration, and apply while draft documents are being
worked on by the applicable group.
5.1 Availability
Documents shall be available via the TC's web page on the
OASIS web site, or via at most one non-OASIS site. Documents
shall be available via HTTP, and optionally via FTP.
Documents may be sent to committee e-mail lists, but any documents
so sent will subsequently be made available via the committee web
site, unless the author specifically informs the committee chair not
to do so. Thus, documents sent to mailing lists should conform to
these guidelines.
The presence of new documents and new revisions shall be announced to
the working group mailing list.
3.2 Naming
Committee documents MUST be named using the format:
"draft-sstc-" + [ subcommittee mailing list acronym + "-" ]
+ short title + "-" + two-digit version + "." + doc format
e.g. "draft-sstc-core-assertions-05.html".
Individual submissions MUST be named using the format:
"draft-" + main author's last name + "-" + short title
+ "-" + two-digit version + "." + doc format
e.g. "draft-morgan-coolidea-00.txt".
5.3 Formats
PDF format is preferred distribution document format. Document
source formats are XML encoded according to the XXX DTD for text,
and Powerpoint source for illustrations (one illustration per
powerpoint slide, one powerpoint file containing multiple slides
per corresponding XML textual source file).
5.4 Content elements
A document must include, at the beginning, the author's names, the
date of submission, the document name including version number, the
name of the working group, and an email address to which comments can
be directed. A document must include, at the end, author contact
information for all authors, including at least an email address for
each.
A document should include, at the beginning, a short abstract, and, if
applicable, a table of contents. Sections and subsections should be
numbered, and usually named also, for ease of reference. A document
should include, at the end, References and Acknowledgements sections.
6. Reference(s)
[0] Bradner, S. "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
[1] Bradner, S. "IETF Working Group Guidelines and Procedures", BCP
25, RFC 2418, September 1998.
[2] "Guidelines to Authors of Internet-Drafts",
http://www.ietf.org/ietf/1id-guidelines.txt
[3] Bradner, S. "The Internet Standards Process -- Revision 3", BCP
9, RFC2026, October 1996.
[4] Rose, M. "Writing I-Ds and RFCs using XML", RFC2629, June 1999.
[5] <OASIS Specifications process document, work that is hopefully
in-progress.>
[6] "OASIS Policy on Intellectual Property Rights (OASIS.IPR)"
available at:
http://www.oasis-open.org/who/intellectualproperty.shtml
[7] Morgan, RL "Bob" "Internet2 Middleware Initiative Working
Group Document Guidelines", internet2-mi-doc-guidelines-00.txt,
25-Jan-2001. Available at:
http://middleware.internet2.edu/internet2-mi-doc-guidelines-00.txt
7. Acknowledgements
This document is largely based on internet2-mi-doc-guidelines-00.txt
by RL "Bob" Morgan. The authors gratefully acknowledge the suggestions of Neal
McBurnett, and information about OASIS practices supplied by Karl Best.
8. Author information
RL "Bob" Morgan
Computing & Communications
University of Washington
rlmorgan@washington.edu
Jeff Hodges
Oblix Inc.
jhodges@oblix.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC