PROJECT: MAC REPLACEMENT PROJECT DOC. TYPE: DESIGN SPECIFICATION DOC NO.: 1 TITLE: DOCUMENTATION PLAN FOR DESIGN SPECIFICATIONS DATE: 10-JAN-79 19:54 AUTHOR: D.B.CURTIS GROUP: DESIGN PROTOCOLS AND STANDARDS SUBJECT: HOW TO GENERATE DESIGN SPECIFICATIONS FILE: DOCPLN.RNO PAGE 2 1.0 OBJECTIVES This document describes the design specification document format. It also describes a CCL command that helps you generate the document. 2.0 DISCUSSION Each design specification has a specific format that is followed. This document is written with this format and serves as an example. There exists an indirect command file that is used to help generate this format. The header page has information about the document itself. This includes author, title, group, and date. The rest of the document has four major sections: 1. objective -- to describe the reason for the document 2. discussion -- to give an overview of the document 3. detailed plan -- to explain in detail the objective of the document. 4. glossary -- to define any new terms It is not a chore to write a design specification unless you make it one. It is a tool to the designers and programmers to help guide them through the development of the system. Therefore, the documents need not be a literary work; however, they must be technically correct! Of course, this does not preclude literary documents, but if you feel that the document generation process takes too long, you should try to reduce the literary quality of the document. These documents are to help us, they are generally not for publication to users! They are to be a complete discription of the project and to serve as a system maintenance guide at the end of the project. My personal preference is to make a short outline either in my head or on paper, and then to type the document in at a terminal. To help you generate the correct format, a CCL command is available. This command is 'DOCUMENT'. It can be abbreviated to 'DOC'. This command causes an indirect command file to run to ask you questions about the formatting of your document. PAGE 3 3.0 DETAILED PLAN Each document generated will be kept in runoff format. The DOCUMENT command causes a set of indirect command files that reside under [17,377] to be executed. These command files automatically generate the document number, the time and date, and help you select the group and document type. This command has been supplied to help maintain standardization of the documents. There may be other documentation tools available at a later time. 3.1 THE FIRST PAGE The first page of the document will contain the following: 1. Document number 2. date 3. author 4. group 5. title 6. document type 7. subject 8. file 3.1.1 document number - This number, assigned by the librarian or automatically by a program is a unique number associated with that particular document. 3.1.2 date - The date is in dy-mon-yr hr:mn format PAGE 4 3.1.3 author - The principal author places his/her/its name here 3.1.4 group - The group, as defined by the organization plan is placed here 3.1.5 title - The title of the document is generated and is a descriptive title 3.1.6 Document type - The document type is one of the following: 1. DESIGN SPECIFICATION 2. TECHNICAL NOTE 3. CHANGE NOTE 4. OTHER Other types of document types will be added as they are needed. 3.1.7 Subject - The subject is a one line description of the subject of the document. The title and the subject should completely indicate the reason for the document. The title is usually shorter than the subject. The subject may be left blank. 3.1.8 File - The file name under which the document exists on the disk is given here. 3.2 MAJOR SECTION HEADINGS There are four major headings that are in any design specification. These are: 1. objective 2. Discussion PAGE 5 3. detailed plan 4. glossary 3.2.1 Objective - This section should clearly and briefly state the intent of the document. 3.2.2 Discussion - This section should explain enough about the detailed part of the plan so that a reader can understand the basic philosophy of the plan. Only major details of the plan should be included in this section. The reader must not be swamped in details. 3.2.3 Detailed plan - This part of the document contains the detailed design of the plan. It should be complete and allow the reader to understand, in detail, what is happening. You may use major section numbers inside this section at your discression (i.e. HL 1 ). 3.3 automatic generation of documents The format described in this document is generated by the command 'DOCUMENT'. This command causes @[37,377]GENDOC.CMD to be run. This indirect command file interrogates you for the required parameters and generates the basic outline of the document for you. The indirect command file automatically generates the document number and the time and date. It will tell you which file to edit when it exits. UIC [17,377] is readable and writable by every user. It contains the following files: 1. GENDOC.CMD This command file is the main file. It determines the type of document that you desire and generates the appropriate calls to other command files. 2. GROUP.CMD This file allows you to select a group that the document is to be placed under. 3. DOCNUM.CMD This file contains the next document number that is to be used. 4. INCDOC.CMD This file updates the document number. PAGE 6 5. DSASK.CMD This file interrogates you for information relevant for a design specification document. 6. DSGEN.CMD This file generates the design specification format. 7. DATTIM.CMD This file generates global variables $TIME and $DATE that contain the date and time strings. 8. DATTIM.TEC This file, when given to TECO will generate the DATTIM.CMD file. 9. DOCS.TRC This file contains a list of the document numbers and other information that is in the header of the files. 3.3.1 glossary - This section of the plan is used to explain your usage of terms. 4.0 GLOSSARY