internet2-document-guidelines-200507

Internet2 Document Guidelines

internet2-document-guidelines-200507
George Brett
1 July, 2005
Comments should be directed to ghb AT internet2.edu.

1. Introduction

The Internet2 Document Library is a web-accessible, keyword-searchable collection of documents and other deliverables produced by Internet2 Groups (e.g., Working Groups, Advisory Groups, Special Interest Groups), or Projects. The materials available in the Internet2 Document Library are publicly accessible and are representative of the Internet2 community's best thoughts on the subject.

These guidelines are intended for documents to be submitted for publication in the Internet2 Document Library. This document outlines basic guidelines for the evolution, format, naming, registration, and archiving of documents generated by Internet2 Groups or Projects. If a document is submitted independently of an Internet2 Group or project, it should still adhere to these guidelines to be accepted into the Internet2 Document Library.

These guidelines are primarily intended for documents produced for the Internet2 Document Library, however Internet2 Groups or Projects may also submit documents developed in the context of external standards processes (e.g. IETF, ITU, OASIS). Such documents should use the procedures appropriate to those processes. If a document is submitted on behalf of an initiative within Internet2, rather than a particular Internet2 Group, the appropriate guidelines should still be followed with that initiative instead having responsibility as the document's steward group.

A statement of applicable intellectual rights should be carefully considered in the context of the Internet2 Intellectual Property Rights framework for all Internet2 products and activities. It is noted that work resulting from Internet2 Groups or Projects is generally 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 Group chair or Project lead at the time of submission.

Internet2 is not a standards body. All documents that are meant to become standards should proceed through the appropriate standards body.

2. Format

Documents submitted to the Internet2 Document Library must abide by a common set of formatting recommendations. These guidelines describe the best practices for document consistency, reference, and availability. While these are requirements for publication in the Internet2 Document Library, all documents created in the context of Internet2 Groups or Projects should consider these guidelines.

A proper header must be included with the name and affiliation of authors and editors, the date of initial document creation, the document name in accordance with section 4 (below), the short name of the group, the long name of the group, and an email address to which comments can be directed. This contact address should not be an Internet2 Group list as these are usually not open to the general public. This external contact address is typically an e-mail alias for the document author(s) and the sponsoring Group chair or Project lead.
A proper footer must be included with appropriate acknowledgements and contact information for all contributors, including at least an email address for each author or editor.
An abstract and a table of contents must be included for large or complex documents.
Relevant citations in Modern Language Association (MLA) or APA format should be included in the footer.

HTML is the preferred document format for submissions. Text and PDF files are also accepted. All submitted HTML should be as clean, compatible, and compliant with W3C standard as possible. The Internet2 Document Librarian may accept, reject, or modify HTML submissions to maintain these goals.

Spelling, capitalization, abbreviations, and vocabulary should be used in accordance with the Internet2 Glossary and Style Guide.
If specific requirement levels are described, they should correspond to the guidelines set forth in the IETF's RFC 2119.
Documents should reference other documents rather than quote them when possible.
Proper acknowledgement of sources utilized or quoted in a document is the responsibility of the document author(s). Internet2 assumes no liability for any failure to do so.
If the document is revised once becoming final, a change log must be included to reflect the differences between an initial publication as final and subsequent revisions.

3. The Document Lifecycle

Internet2 Group documents begin as drafts, proceed through one or more revisions, and upon completion of an approval process as defined by the sponsoring/steward Internet2 Group or Project, are published as final documents. Documents already admitted to the Internet2 Document Library may be updated following the completion of the revision process, at which point the updated document replaces its predecessor. The previous publication remains in the Internet2 Document Library as an obsolete publication that will refer to its successor. The submission of the newer document must specifically reference the URL of the document it is intended to supercede.

Documents may be submitted either as individual submission documents or as Internet2 Group or Project documents. An individual submission document represents only the opinions of its author or editor and contributors, and need not complete the workgroup review requirements for Internet2 Group documents. An Internet2 Group or Project document is intended to reflect the consensus of its steward group. Each document must have at most two primary authors or editors. Other contributors should be acknowledged in a separate “Acknowledgements” section contained near or at the end of the document.

The scope and content of documents submitted on behalf of Internet2 Group or Project should typically be guided by the sponsor/steward group's charter or otherwise approved by the group chair or lead. Individual submissions may discuss any topic relevant to Internet2's ongoing efforts. Acceptance of documents for group stewardship is determined by Group chair or Project lead. An individual submission document may later become an Internet2 Group document.

It is intended that all documents submitted to Internet2 Groups or Projects complete the following phases:

Development

Draft Documents
All drafts must have an assigned expiration date. Six months is suggested as a reasonable lifetime for any individual draft document. If a new version of a draft is issued, it should have a corresponding delay in its expiration.
Working Group, Advisory Group, Special Interest Group, or Project Review
Members of the sponsoring/steward group or project should review the draft and appropriate revisions should be made as appropriate. Once the draft reaches a satisfactory state, the sponsoring/steward group or project should formally approve the draft, at which point it proceeds to external review (as appropriate at the discretion of the sponsoring/steward group or project lead). It is expected that the revision process will take no more than a year. Individual submissions do not need to complete this step, but should consider consulting appropriate Internet2 Groups or Projects during external review.
External Review
The draft should be presented to appropriate external individuals and communities for review (as appropriate at the discretion of the sponsoring/steward group chair or project lead) and comment. Subsequent revisions may occur at this point.

Update

Revision
If a publication in the Internet2 Document Library requires revision, a new draft should be created – i.e. the document goes back into draft status and repeats the editing/approval process. The draft must have an assigned expiration date and must be identified as an intended replacement for a specific publication. Draft file name conventions are followed; version numbers are reset.
Workgroup Review
Members of the sponsoring/steward group or project should review the draft and appropriate revisions should be made. Once the draft reaches a satisfactory state, the sponsoring/steward group or project should approve the draft. A second external review may follow. Once review is complete, the revised publication replaces the original publication in the Internet2 Document Library with a revised date as appropriate.

The basis on which documents are promoted through the document lifecycle should be defined by Internet2 Groups or Projects with the approval of the appropriate Internet2 Area Director. Individual submissions should proceed in accordance with the development cycle for Internet2 Group documents but may omit workgroup reviews.

4. Filename Conventions

This section outlines the filename conventions you should follow when submitting both draft documents and final publications to the Internet2 Document Library. Document filenames should be named according to their progress in the sponsoring Internet2 Group or Project’s document evolution model. A document is a considered a draft until it has been formally approved by its sponsoring/steward group or project. If a document is submitted to an initiative within Internet2 rather than a particular Internet2 Group or Project for naming purposes, the initiative serves as that document's sponsoring/steward group through its evolution. If a document is submitted generally to Internet2, then the Internet2 Group or Project name may be omitted.

Filenames for Draft Documents:

Internet2 Group draft document filename format:
draft-internet2-<group-short-name>-<short-doc-title>-<two-digit-version-number>.html

Note: the “two-digit-version-number” should begin at “00”
example: draft-internet2-mace-dir-eduperson-00.pdf
               draft-internet2-mace-dir-eduperson-01.pdf
                draft-internet2-mace-dir-eduperson-02.pdf
                etc.

Note: when a document that has been approved as final goes back into draft, the version number resets to -00.

Filenames for Draft Individual Submissions

draft-<author-name-or-initials>-<short-doc-title>-<two-digit-version-number>.html

example: draft-morgan-perpetual-motion-00.txt

Filenames for Final Documents

Internet2 Group document:
"internet2-" + working-group-short-name + "-" + short-title + "-" + YYYYMM date + "." + format (**Same as above)

example: internet2-mace-dir-eduperson-200201.pdf

Individual submission:
author-name-or-initials + "-" + short-title + "-" + YYYYMM date + "." + format (**Same as above)

example: morgan-perpetual-motion-200209.html

If multiple versions of a document are submitted in the same month, they may be differentiated by appending lowercase letters to the date as appropriate.

example: internet2-mace-dir-eduperson-200201a.pdf

5. Registration

All documents published by Internet2 Groups or Projects should be submitted in draft form to the Internet2 Document Library (http://docs.internet2.edu) for registration when the document enters the external review phase. The Internet2 Document Library may decide whether to accept or reject the document based on the guidelines set forth in this document, at the discretion of the Internet2 Librarian or Manager of Information and Knowledge Management.

Draft documents sent to Working Group e-mail lists should subsequently be made available via the Internet2 Group or Project website, unless there are extenuating circumstances and an author specifically informs the chair not to do so. Drafts sent to mailing lists should conform to these guidelines.

When a document is accepted by the Internet2 Document Library, it will be made publicly available on the Internet2 website and will be entered into the Internet2 Document Library database.

The presence of new documents and new revisions must be announced both to the appropriate Internet2 Group or Project mailing list and submitted to the Internet2 Document Library. If a revision to a document in the Internet2 Document Library is approved, this revision must be submitted to the Internet2 Document Library.

6. Acknowledgements

Contributions from the Middleware Architecture Committee for Education were greatly helpful in the development of these guidelines. The author wishes to additionally thank Nate Klingenstein, Bob Morgan, Greg Wood, and Neal McBurnett for their suggestions.

7. References

Morgan, R.L. "Internet2 Middleware Initiative Working Group Document Guidelines", http://middleware.internet2.edu/internet2-mi-doc-guidelines-00.txt.
Bradner, S. "IETF Working Group Guidelines and Procedures", BCP 25, RFC 2418, September 1998.
"Guidelines to Authors of Internet-Drafts", http://www.ietf.org/ietf/1id-guidelines.txt.
Bradner, S. "The Internet Standards Process -- Revision 3", BCP 9, RFC2026, March 1997.
Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC2119, October 1996.
The Internet2 Intellectual Property Rights framework, http://members.internet2.edu/intellectualproperty.html, 9 April 2005
Internet2 Glossary and Styleguide, http://www.internet2.edu/info/i2gsg.html, 24 September 2004

8. Author Information

George Brett
Internet2
email: ghb AT internet2.edu.