[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: document guidelines example
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC