[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Comments on document guidelines
I don't know if this ever got more widely distributed. I sent these
comments to Bob Blakley a week back.
* * *
Here are just a few comments on the SSTC Document Guidelines; for the most
part it's perfect.
At 12:52 AM 1/31/01 -0800, Jeff Hodges wrote:
>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.
I think saying they'll be available by HTTP (or not saying anything after
the first sentence) is sufficient. The FTP reference feels like an IETF
holdover.
>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.
I would prefer that we encourage document publication to happen solely
through putting it on the website, and then mailing out the URL (without
making it a crime to mail documents). Having tons of documents flying
around in email as a regular way of getting work done is unwieldy, and I'd
like to "train" people to have a bookmark for our website's various
important areas.
>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".
For HTML documents, any chance we can standardize on either .htm or .html,
but not both? It would be annoying for people to guess wrong on the
extension, when the rest of the filename is so well structured.
>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).
Was PDF the agreement of the folks who collaborated on these guidelines? I
thought we were going for HTML.
>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.
I would like to see all the "metadata," including author contact
information, at the top so that it's all in one place. Of course, if we
use sufficiently structured XML (e.g. XMLspec or a derivative), we can
generate the output to put this stuff in any order we like.
FWIW, here's what W3C documents typically have in the header; these
examples are taken from http://www.w3.org/TR/REC-xml and they're all
formally covered in the XMLspec DTD. I think it would be nice to have at
least all those with *:
*Title (e.g., "Extensible Markup Language (XML) 1.0 (Second Edition)")
Type of document (e.g., "W3C Recommendation")
*Date of publication (e.g., "6 October 2000")
*Official URI of publication (e.g.,
"http://www.w3.org/TR/2000/REC-xml-20001006")
Generalized URI of latest version
URI for most recent previous version
*Authors/editors and contact information
Copyright statement
*Abstract
*Status of This Document
This week I will attempt to make a derivative of XMLspec (or simply its
stylesheets) that might meet our needs.
>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.
Sections and subsections should always be both numbered and named. A TOC
doesn't work without names...
You might want to say something about appendices clearly indicating whether
they're normative or not. XMLspec has a provision for this.
>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
Should the Guidelines say something about issue numbering, a la Dave
Orchard's suggestion and the current usage of the use-case group?
--
Eve Maler +1 781 442 3190
Sun Microsystems XML Technology Center eve.maler @ east.sun.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC