document guidelines example

[RL 'Bob' Morgan <rlmorgan@washington.edu>]

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