Navigating RFCs:
Internet Technology Document Suites

What is the set of current documents with the technical details of a particular service? Answering this question can be daunting, especially when the service has a long history, filled with formal changes, enhancements, errata notes and esoteric lore. This Document Suite wiki provides a home for collaborative, on-going efforts at recording such information about popular Internet capabilities. An Internet service is described by a collection of specification and support documents, along with informal commentary to guide development, deployment, operations and use. This collection forms a Technology Document Suite. Occasionally there is an attempt to develop a document that, itself, describes the current set of documents for a service. These are rare and incomplete efforts, helpful but insufficient, and quickly obsolete. As a wiki, the current effort permits on-going, incremental revision to track the evolution of a service.

The term "service" is meant as a high-level, integrated reference, such as "the Web", email, or IP. Some services are quite broad and have subordinate services. Ultimately, a service's document Suite can consist of many parts, covering:

• History
• Requirements
• Overview
• Foundation specification, such as architecture or model
• Component specification, such as functions and facilities
• Protocol and format specifications
• Registration of operational parameters
• Configuration details
• Management details
• Development and conformance guidelines
• Deployment and Operations guidelines
• Usage Guidelines
• Reference (open source) implementations

The wiki table entries describe distinct sub-services or functions within an integrated service. Citations are not limited to RFCs. Reference to web sites, wikis, books, other standards, or any reference that is helpful is encouraged.

Goal

• The current goal for this wiki is to develop the form of the tables that is needed, so that the community can easily contribute and use information.
• In particular, the question is what are the cases that the current form does not cover or does not cover adequately?
• The goal, then, is to discuss enhancements to the form of this wiki.

There will be a mailing list for this; in the interim, please send questions, comments and suggestions to:

Dave Crocker <dcrocker@bbiw.net>

Almost any interesting service comprises a set of specifications. This means that the service will need a subordinate Suite table.

The major challenge in developing a service Suite appears to be choosing what to list in the "Components column". The rows formed by these choices present the primary conceptual organization of the service. The second challenge is determining when to define subordinate Suites (in the third column). This establishes a hierarchy to the service structure. These choices need to match both the way the technology specifications have been written and the likely manner of using specifications needed by implementers and operators.

Sample

A document Suite is of the general form:

Example:  Ultimate Widget Suite

Components	Documents	Sub-Suites	Comments
General	Foundation (RFCabc)		A service for the exchange of ultimate widgets
Data	Format (Meta-Form - RFCdef) Registration (Fields - RFCghi) Registration (IANA)	Widget Fields Widget Object Security	Each widget has fields that are individually defined. Field registration might be better to put in the Fields Suite?
Exchange	Protocol (RFCjkl) Registration (Port 000 - IANA)		Perhaps there should be a pointer to the TCP or UDP Suite?
Management	Format (RFCmno) Registration (Port 587 - IANA)		MIB for widgets

Background

This wiki was prompted by a Slashdot article which has also prompted graphically-oriented work by Ray Bellis that is used in this wiki. The set of Internet technical documents has become complex and confusing. The problem of guiding new readers to a correct and coherent set of these documents is overdue for attention.

Table Legend

A table specifies one or more services, or one or more components of a service. It is organized to list a series of components by row. For each entry, the documents that apply to everything related to that entry are listed in the References column. Constituent entries are listed in the neighboring Suite column.

Suite Component

Each row of a Suite table specifies an entry for a service component.

Technology Service Components:	The name of the service or component. A service provides a complete capability. To be useful, a component must be incorporated into a service. One service can be incorporated into another. Note that organization of the entries within a Suite serves as a principle summary of the organization of the capability being described by the Suite.
References:	Direct citations to documents, online sites or the like for discussion, overview, foundation, guidance, or even complete specification. (See the References list, below.) Notationally, for a Suite branch -- a Suite and its sub-Suites -- this specifies leaves..
Sub-Suites:	References to subordinate tables. These list sets of components that are related to the (superior) service or component. Notationally, this specifies transit links down the Suite branch.

In addition to technical specification documents, a number of other types of documents and sources of information are common. An entry should include whatever citations are helpful and label them however appropriate. For the types of citations that are common, standardized labeling will help the reader to more easily understand the table.

To that end, here is a suggested form to citations and some common labels to use:

References

These are some common types of references. It will help to converge on regular terminology for these types and to make references generally follow a consistent form.

Form

A reference should be one of the forms:

{Reference type} ( {label - {citation} )

{Reference type} ( {label} )

{Reference type} ( {citation} ) 

where:

Reference Type:	See the following table, to characterize difference style of documents and information
Label:	Any short string of text that will help the reader to distinguish among a set of related references. Often this should be a terse form of the document title or description of its contents. Sometimes, this information and the citation are merged,
Citation:	The information needed to retrieve the information, optionally encoded as a citation label and associated URL. For example, the RFC number and a link to the RFC archive.

Examples:

Foundation (RFC5598)

Registration (Port 587 - IANA)

Registration (Header Fields - RFC4021)

Type

Group:
Activity:	A service is usually created through independent community effort that begins before standardization, to formulate community need, and continues afterwards, to promote adoption and enhancement. This entry refers to the independent website that represents such an effort.
Standards:	The web page associated with standards-oriented effort for this service. For this wiki, this will usually be the IETF working group page. Note that more than one standards organization can be involved in a service, such as to provide component capabilities.
Discussion:	Free-form consideration of a topic.
Introduction
Overview:	Any document that provides a summary tutorial about the service
Bellis:	A citation for a graph that depicts the set of documents related to this service. Ray Bellis (Nominet) has developed a tool which formulates a visual representation of related RFCs, per his discussion. Yellow nodes are active documents and gray are historic. Curved corners are specification standards; sharp corners are operational.
Foundation:	Specifies the an ecompassing view of the service, with aframework, model, roadmap, architecture or the like, for a services's components, their relationships and interactions (protocols).
History:	Discussion of the background and experiences with the service.
Parent link:	(Just being diligent, here.) Complex service Suite structures might warrant pointing from a subordinate Suite to its parent, to help the reader recover context.
Specification
Protocol:	Specification of a networking protocol
Format:	Specification of the syntax and/or semantics of data
Register:	For a protocol to become a service, it needs access registration, which specifies how to reach the service, from among an extensive suite of services. An example is a TCP port number. This entry points to the registration specification for this service.
MIB:	Specification for a Management Information Base for the associated protocol.
Profile:	Tailored use of the service.
Deploy
Develop	A discussion about activities that aid in the creation of interoperable implementations.
Operations:	The document provides discussion and possibly recommendations concerning efforts to install and run the service.
Reference:	Open source, reference implementation software.
Administrative
Author:	Contact information for person or role that created the Suite

Suite Creation

This section provides suggestions about the process of creating a new Suite. Since this wiki is still under initial development, the guidance is, at best... nascent. To the extent that you see flaws in the guidance, please treat that insight as the most valuable part of your effort and communicate it to others working on the wiki. At the least, please send a note to Dave Crocker.

Component Sequence

A Suite organizes and lists a combination of citations and sub-Suite pointers. It is formed as a series of rows, with the focus of the row being defined by the left-most column. That column defines the different "components" of the Suite. Obvious choices for guiding the organization of a list of components are:

Architectural parts:	how its design is structured
Functional parts or Roles:	how it is implemented
Phases of processing:	how its use can be divided into steps

The organization of a Suite can offer a reader important insight to the nature and details of a service. So, choosing the right organization can take some effort. Sometimes it will help to combine these approaches, such as a Suite organized by Function that then calls on Suites organized along architectural or processing lines, as in DNS Role and DNS Technology.

NOTE:

In most cases, simply listing protocol names as the sequence of Suite component labels is likely to be the least helpful approach. Use the protocol name for the citation or Suite reference. For the component label, consider using text that describes the nature, purpose or function being supplied.

Competing Suites

Because the organization of components in a Suite imparts a particular perspective on a service, it is possible that an alternative – and equally reasonable – perspective will lead to an alternative organization of components. It is also possible that it will not be obvious which perspective is superior for use in the wiki. It is even possible that it will never be possible to make the choice.

That's ok. Make two, competing Suites! The wiki makes this easy and the ultimate winner – if one ever is determined – can be left to the crucible of actual use.

In fact, the competition can turn out to be complementary, with one perspective using the other. Take a look at DNS Role versus the "subordinate" DNS Tech Suites.

Reference vs. Sub-Suite

The choice between listing a series of citations in the References portion of a component entry, versus defining a sub-Suite, seems to depend on the complexity created by the set of citations. If there is salient information to be supplied by creating the organization of a sub-Suite, or if the set of citations is simply too complex for a single References cell, then do use a sub-Suite. On the other hand, sub-Suites mean increasing the complexity of the Suite hierarchy. Less hierarchy is preferred.

Reference Form

A reference contains 2-4 bits of information. The two that are required are the 'type" of the reference and the pointer to it. The type of a citation tells the reader what the citation is generally useful for. This is the first field because it appears to be the most useful to an implementer trying to filter among a set of references. The pointer gets them to it. One optional field is text that will help the reader distinguish among a set of closely-related citations, as well as provide them with a popular tag that others will use to refer to the citation. The other optional field distinguishes between the human form of a citation and the online form.

For RFC citations, It is probably best to refer to the datatracker.ietf.org version, since this also lists context around the document, including errata and process history.

Include vs. Exclude

The goal of this wiki is to provide potential implementers with the information they need now. In general, this means that deprecated or historical information typically should not be included. A particular example would be specifications that have become obsolete. Obvious exceptions will be documents that are deemed essential for a current implementer to understand, in spite of the document's formal status. However, the goal of the wiki means that it is just as important to exclude extraneous information, as it is to include essential information, lest an implementer waste time tracing down unproductive references.

A Typical Suite Creation Sequence

Even a relatively complex service will require only a few hours to complete an initial version of a Suite. An approach that seems to be relatively efficient is:

1. List relevant documents.  This gets incrementally better as the effort proceeds, of course. So the first round should be extensive but does not have to be 100% complete.
2. Try to loosely organize the documents into meaningful sets. Examples to review - email, dns, ldap.
3. Develop labels for those sets of documents that explain why they make sense as a group.
4. Organize the sets into Suite rows and sub-Suites.
5. Iterate.  Reviewing tends to produce new insights about how things should be put together.

Table of Suites: Primary Internet Services

(Note how many services still need to have Suites supplied. Please take that as an intivation!)

Email Suite

MIME Content Suite

Message Security Suite

SMTP Suite

SMTP Extensions Suite

IMAP Suite

POP Suite

DKIM Suite

Facsimile Suite

VPIM Suite

EAI Suite

DNS Role Suite

DNS Core Tech Suite

DNS Authoritative Tech Suite

DNS Name Tech Suite

DNSSEC Suite

LDAP Suite