OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

security-services message

[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