[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