Re: document guidelines example

["Eve L. Maler" <eve.maler@east.sun.com>]

Bob, this is great stuff.  May I suggest you rework it for our purposes, 
send it to the list again, and make a proposal at our telecon that it be 
adopted by the group?

I've just asked Karl Best for info on the OASIS FTP site, and hope that 
Marc Chanliau will have a plan soon for organizing resources on our web area.

         Eve

At 12:20 AM 1/23/01 -0800, RL 'Bob' Morgan wrote:

>I wrote the doc below recently for another group I'm involved in, and
>thought it could be useful as an example of the kind of guidelines we
>might have for OASIS Sec-TC documents.  Obviously it borrows heavily from
>IETF practice.  The applicable stuff is in section 3.  Feel free to use
>any portion or discard ...
>
>  - RL "Bob"
>
>---
>
>
>Internet2 Middleware Initiative Working Group Document Guidelines
>
>draft-internet2-mace-doc-guidelines-01.txt
>RL "Bob" Morgan
>January 8, 2001
>comments to:  mace@internet2.edu
>
>This document is an Internet2-Draft and is in conformance with
>relevant Internet2 document standards (i.e., itself).
>
>
>Abstract
>
>This document specifies document-handling practices for Internet2
>Middleware Initiative Working Groups.
>
>
>1.  Introduction
>
>This document recommends standards for name, format, and availability
>of documents that are being worked on in Working Groups of the
>Internet2 Middleware Initiative (and, potentially, other areas of
>Internet2).  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 Internet2 process.
>
>The standards expressed here are for documents produced specifically
>for use in Internet2 Working Groups.  Internet2 Working Groups may
>also produce and use documents developed in the context of other
>standards processes (in particular the IETF standards process), in
>which case those documents should use the procedures appropriate to
>those processes.
>
>While a comprehensive property-rights statement (e.g., section 10 of
>[3]) is out of scope for this document, it is noted that work
>submitted to Internet2 Working Groups is intended for the benefit of
>the Internet2 community and the general public.  Any known
>restrictions on the distribution and use of submitted documents or
>technologies must be brought to the attention of the Working Group
>chair at the time of submission.
>
>
>2.  Document evolution model
>
>This recommendation supports a simple model of how documents move from
>initial ideas to final, approved products.
>
>Documents begin as drafts, proceed through a number of revisions, and
>finally, upon approval by the working group, are published as final
>documents.  Document names reflect this process.  Draft documents are
>not permanent, and may be superseded or removed at any time.
>Completed documents that are intended to be permanently referenceable
>should be published as final documents.  (Note that Internet2 does not
>have a formal method, ala the IETF's RFC series, for publishing its
>final-form documents, and this document does not define one.)
>
>A distinction is made between "individual submission" documents and
>"working group" documents.  An individual submission (which may of
>course be submitted by more than one person) represents only the
>opinions of its authors.  A working group document is intended to
>reflect the (rough) consensus of the working group.  The topics of
>working group documents will typically be specified in the working
>group charter or are otherwise agreed upon by the group, while
>individual submissions may be on any topic relevant to the work.
>Decisions about accepting documents as working group documents are
>made by working group chairs.  An individual submission may later
>become a working group document (and vice versa).  Document names
>reflect this distinction.
>
>
>3.  Document guidelines
>
>These guidelines apply to all documents submitted for working group
>consideration, and apply while draft documents are being worked on by
>the group.
>
>3.1  Availability
>
>Documents shall be available via the working group's web page on the
>Internet2 web site, or via at most one non-Internet2 site.  Documents
>shall be available via HTTP, and optionally via FTP.
>
>Documents may be sent to working group e-mail lists, but any documents
>so sent will subsequently be made available via the working group web
>site, unless the author specifically informs the WG 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
>
>Working group documents must be named using the format:
>
>    "draft-internet2-" + working group name + "-" + short title
>      + "-" + two-digit version + "." + doc format
>
>    e.g. "draft-internet2-eduperson-schema-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".
>
>3.3  Formats
>
>Plain ASCII text and HTML are preferred document formats (HTML
>documents may have GIF or JPEG figures).  PDF format is acceptable.
>Vendor-specific formats such as Microsoft Word and Excel formats are
>discouraged.  Microsoft PowerPoint is actively discouraged.  (A method
>for preparing documents in XML for subsequent conversion to other
>formats is described in RFC2629 [4].)
>
>3.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.
>
>
>4.  Reference(s)
>
>[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.  Acknowledgements
>
>The author gratefully acknowledges the suggestions of Neal McBurnett.
>
>
>6.  Author information
>
>RL "Bob" Morgan
>Computing & Communications
>University of Washington
>rlmorgan@washington.edu

--
Eve Maler                                          +1 781 442 3190
Sun Microsystems XML Technology Center    eve.maler @ east.sun.com