Documentation Conventions

Purpose

The "MULTICS SYSTEM-PROGRAMMERS' MANUAL" (MSPM) will be used and maintained by the system programmers of the 645 Multics time-sharing system. The material which will be included in this manual will be everything a system programmer needs to know about the system in order to use any part of the system and to add to or maintain the system. This includes rules and standards of how things should be done, formats of all files and data bases, write-ups of subroutines, interfaces of modules (what they call, what calls them, and what data they need). What it does not include is a theoretical discussion and proposals of how life ought to be and what might be done but isn't.

Manual Design

The table of contents shows how the manual is divided into sections on a functional basis. In fact, the table of contents attempts to be an outline of the system. Every section may have a O. subsection which describes any general philosophy or rules about the section. The section labels are of the format BX.YY.ZZ.

B is the label for this manual (being the second in a series of 2)
X is the major section label of a single alpha character.
YY is a subsection label of 1 or 2 decimal digits (O-99).
ZZ is a subsection label of 2 decimal digits (00-99).

Original issues and significant revisions will be distributed by the persons in charge of documentation at Bell, GE and MAC, respectively. Each system programmer is responsible for maintaining his manual in up-to-date condition by inserting distributed sections. Each write-up should be able to stand alone; that is, a section of this manual should not reference outside the MSPM for additional information. A write-up may, however, reference other writings in order to give appropriate credit. If ideas are copied from previous memos, or repository documents, the documents may be copied also, if needed to explain the ideas.

Each write-up should follow a standard form wherever possible. The first two sections (Identification and Purpose) are required for each write-up but the other sections are optional. Identification should include the identification of what is to be described as well as the author's name. The Purpose should tell the reader what, why, and whether he is interested enough to continue reading. Wherever possible, the front of each write-up should be written for the user and should include the usage, references and restrictions. The second part of the write-up should be for the system programmers and should include details of methods, interfaces, data bases and anything else of note. Someday in the future, the user's information may be extracted from this manual in order to prepare a user's manual.

New Write-Ups

Since new write-ups frequently imply new design decisions, there must be some mechanism whereby faulty decisions cannot be cast in concrete nor propagated indefinitely merely because they appeared in print.

However, in contrast to previous practice, any section of the MSPM which is distributed by the manual editor is automatically approved. In particular, new write-ups must be approved by an appropriate sub-project leader before inclusion in the manual. The list of authorized sub-project leaders and their areas of responsibility will be designated by the triumvirate and given to the manual editor: currently Bob Graham. The editor is responsible for initiating and expediting write-up reproduction and distribution; the editor is also authorized to direct sub-project leaders to have write-ups revised in order to improve clarity (but not technical content).

It is the responsibility of the editor to maintain for the triumvirate a history of who approved each MSPM section and its publication date. Whenever a section is revised, it must be revised in its entirety, a new publication date supplied and minor changes marked in the right margin; sections which have major changes should be marked as such immediately under the publication date. Beneath the publication date there should appear a brief parenthetical note with the number and publication date of all previous versions of the section which are superseded. Revisions should be circulated with a cover page indicating the overall significance of the changes. Finally, all sections should be legibly reproduced by xerox or multilith techniques, if possible; there is no longer any significance to the color of the reproduction.

Editing the Manual

Every system programmer is responsible for the accuracy and up-to dateness of the entire manual. This means that anyone who finds an error, an unworkable idea, or anything which should be changed should contact the author and send a corrected copy to the editor. No one is free to pass-the-buck and say that it's not his or her responsibility. All corrections as well as new write-ups must be submitted to the editor who is charged with the responsibility of not allowing changes to the manual without approval of authorized sub-project leaders. It is recommended that corrections be marked on a copy of the write-up for submittal to the editor, since the editor can Accept No Verbal Orders.

A particular typing format is recommended for sections. Sections should if possible be prepared in machineable form using either TYPSET or the off-line Flexowriter paper-tape technique. (Eventually it is expected to put the MSPM on-line with Multics.) The recommended form of sections and appropriate stylistic conventions are given in following subsections.

Library links: Papers | Articles | Dev Docs | Source | Simulator