Recommendations for facility documentation
What network services should document for users and programmers
Watson, R.W., "Recommendations for facility documentation", RFC 118, DOI 10.17487/RFC0118, April 1971, <https://www.rfc-editor.org/info/rfc118>.
@misc{rfc118,
series = {Request for Comments},
number = 118,
howpublished = {RFC 118},
publisher = {RFC Editor},
doi = {10.17487/RFC0118},
url = {https://www.rfc-editor.org/info/rfc118},
author = {R.W. Watson},
title = {{Recommendations for facility documentation}},
pagetotal = 2,
year = 1971,
month = apr,
} RFC text
Network Working Group Richard Watson
Request for Comments: 118 Stanford Research Institute (ARC)
NIC: 5830 16 April 1971
RECOMMENDATIONS FOR FACILITY DOCUMENTATION
INFORMATION REQUIRED FOR EACH SERVICE AVAILABLE TO THE NETWORK
There are two classes of information which a site needs to provide
for each service or process it makes available over the Network:
i) information required by system programmers in order to
establish a connection to the facility
ii) information required by a user to gain access to and use the
facility
The above two basic kinds of information which need to be in each
facility description will comprise a "functional document" (see RFC
115, NIC (5822,) for a description of functional documents and
recommended procedures for updating them).
The information required by user site system programmers may be a
detailed document or a reference to a document containing a protocol
common to several facilities or some combination of the above. All
information required such as connection socket numbers, message
formats, and character set information must be included. Two
examples of system programmer type information are RFC 74, NIC
(5417,) and RFC 105, NIC (5775,) prepared by James White of UCSB.
The information required by user site users is of three types:
a) information unique to Network users of the facility
b) information in common between Network users and server site
users of the facility
c) information unique to particular Network user site.
The information of type c) would be prepared by the user site from
the information provided by the server site. An example might be
keying conventions required in order to send certain codes to the
server site.
Future documentation will probably be written with information types
a) and b) above integrated in one document, but initially server
sites will probably have user manuals or documentation for their
local users and will need to write a short document giving any
additional information required for Network users. This information
will vary, but might include a different login or control card
sequence, varying echo or syntax for user sites operating with
character at a time, line at a time, server site or user site echoing
and so forth. Some features available to server site users may not
be available to Network user site users or certain features may
behave differently.
In addition to the above types of information, there should be
instructions to the user on how to obtain help or answers to
questions about using the facility.
Information about how to obtain administrative access (charge
numbers, etc.) to a site should be contained in the document, ARPA
Network Current Guides to Network Facilities, NIC (5148,). This
information is being collected by BBN. This document will in turn
contain references to the functional documents containing detailed
descriptions of available Network facilities and how to use them.
Even if there are no special conventions or information unique to a
Network user as opposed to a server site user, this fact should be
explicitly stated in order to avoid confusion or uncertainty.
NETWORK INFORMATION CENTER POLICY ON DISTRIBUTION AND UPDATING OF
DOCUMENTATION
The Network Information Center will distribute and maintain one copy
of each functional document describing a facility in each Network
Station NIC Collection. For this purpose we would appreciate it if
100 copies of each manual and set of manual updates, when they occur,
could be sent to the NIC. Users at sites desiring their own copies
of user documentation can obtain them either directly from the server
site or by copying the master in their local NIC Collection. In
order that users may know where to obtain additional copies of the
documentation, an address and a price, if any, should be included in
the information about each facility.
[ This RFC was put into machine readable form for entry ]
[ into the online RFC archives by Mirsad Todorovac 10/98 ]
AI ELI5
On this page
§1Documentation for Network Services
Each service available over the ARPANET needs to publish two types of information. First, system programmers at other sites need technical details: the connection socket numbers, message formats, character set information, and protocol details required to establish a connection. Second, users at other sites need to know how to actually use the service: login sequences, command syntax, and how the service behaves differently for network users versus local users.
A network service is like a restaurant. Programmers need the address and phone number. Users need to know the menu and hours.
§2User Information Requirements
User information should address three categories: information unique to network users (e.g., different login procedures), information shared between network and local users, and local site customizations for network use. Initially, sites would adapt their existing local user manuals by adding a supplement for network users covering differences in echo behavior, character handling, and available features.
Even when there are no differences between network and local use, this should be explicitly stated to avoid confusion.
Tell network users what is the same as local use and what is different. If everything is the same, say so clearly.
§3Distribution and Management
The Network Information Center would distribute and maintain one copy of each functional document at each Network Station. Sites would submit 100 copies of their documentation to the NIC, which would make them available in the NIC Collection. Users could obtain copies directly from the service site or from their local NIC Collection. Each documentation package should include contact information and pricing for additional copies.
One central library (the NIC) would keep a copy of every service manual. Sites send their documentation there, and users can copy it from the library.