Contact us Heritage collections Image license terms
HOME ACL Associates Technology Literature Applications Society Software revisited
Further reading □ Overview □ Project Note 1 □ Project Note 6 □ Project Note 7 □ Project Note 8 □ Project Note 9 □ Project Note 10 □ Project Note 11 □ Project Note 12 □ Project Note 13 □ Project Note 14 □ Project Note 15 □ Project Note 16 □ Project Note 17 □ Project Note 18 □ Project Note 19 □ Project Note 20
ACD C&A INF CCD CISD Archives Contact us Heritage archives Image license terms

Search

   
⟶ ACL ⟶ Literature ⟶ Progress Reports ⟶ FR80 Project :: FR80 Project Notes
⟶ ACL ⟶ Literature ⟶ Progress Reports ⟶ FR80 Project :: FR80 Project Notes
ACL ACD C&A INF CCD CISD Archives
Further reading ⇓

□ Overview
□ Project Note 1
□ Project Note 6
□ Project Note 7
□ Project Note 8
□ Project Note 9
□ Project Note 10
□ Project Note 11
□ Project Note 12
□ Project Note 13
□ Project Note 14
□ Project Note 15
□ Project Note 16
□ Project Note 17
□ Project Note 18
□ Project Note 19
□ Project Note 20

Project Note No 1: Documentation

FR80 Project Branch

27 November 1974

1. PAPER SERIES

There is a need for a number of paper series concerning the FR80, its associated software and operation. To a large extent, the content and required distribution decide where a paper is to go. The initial series are defined below.

1.1 FR80 User Notes

User Notes will contain general information about the FR80 which is required by graphics users. The distribution will be to all ACL users and Rutherford Laboratory graphics users. If papers on the FR80 are of interest only to 1906A or 360/195 users, they will be produced as 1906A or 360/195 User Notes. Again, it is important that Rutherford users get copies. This series should be the only one required by users. It is possible that certain Technical Papers might be needed by one or two special users.

1.2 FR80 Technical Papers

These contain a record of design decisions and program descriptions. If a series exists already for a particular package, information will continue to be output there if it is specific to that package. Technical papers for packages like GROATS and POLYGRAPHICS will be put in this series. Only final designs and firm descriptions will be included here. Distribution may be to some people not in the Branch.

1.3 FR80 Discussion Papers

This series will contain ideas and half-formulated papers for discussion before a final decision is made. These papers are likely to be modified and finally issued in one of the other series. If it is likely that several iterations will take place on a single paper, the earlier ones may well be passed round the Branch in an untyped form. Distribution will be be to Branch members only.

1.4 FR80 Project Notes

The main purpose of this series is to record progress and describe organisation. The regular fortnightly meetings will often result in a set of actions on individuals which will be listed here. The results of discussing one of the previous papers may be recorded here prior to a proper Technical Paper or User Note. Distribution will be to Branch members only at first.

1.5 FR80 Operator Notes

This series is primarily designed for information relevant to the operation of the FR80 and its ancillary equipment. This should contain operating instructions and the standard settings of parameters. Distribution will be to Branch members.

2. LAYOUT

There will be a standard layout for papers in all series. This paper indicates some of the features. Some of the points to remember are:

  1. Each paper of any size is to be split up into major sections with titles in capital letters.
  2. Sub-sections will be numbered and have their headings underlined with the initial letters of major words in capitals.
  3. Further sub-division at the 1.1.1 level is only necessary in a very large paper and, in this case, the heading will be in lower case apart from the first letter. Both the number and heading will be underlined.
  4. Major sub-divisions and lists will be headed by (1), (2) (3), etc. Further sub-divisions will be headed (a), (b), (c), etc.
  5. A colon should be used after 'for example', 'as follows' etc, and not :-
  6. There will be consistent spelling of standard terms. For example:
    1. 360/195, 1906A, FR80, PDP15, SD4020
    2. the two tape formats will be described as SD4020 and FR80 (rather than native mode)
    3. names of packages will be in upper case, PMN's FORTRAN package will be called and written SCFOR.
    4. the following are single words on: the 1906A: filename jobname username filestore lineprinter semicompiled
    5. the form of abbreviation for time and store should be: 10 mins 220K words 20M chars 24-bit words
    6. abbreviations such as: eg 6A Exec are not encouraged.

If drafts can be written according to the above, it will help considerably in producing correct and consistent typed papers.

PREPARATION OF DRAFTS FOR TYPING

WRITE ON A LINED PAD
Using old lineprinter output saves very little money. Any saving is almost certainly lost if this results in unnecessary re-typing. The typists use a ruler to mark their position and, consequently, if the draft does not line up, lines may be missed, If it is likely that you are going to modify the draft extensively, write on every other line to start with. Oxford Pads for this purpose can be obtained from JBC or Stationery.
2. WRITE IN INK
Ink is clearer even if you make errors and have to cross them through. Pencil is hard to read and rubbings out make things worse.
3. INSTRUCTIONS TO TYPISTS SHOULD BE WRITTEN IN A DIFFERENT COLOUR
Leave a margin on one side of the paper and instructions will show up clearly.
4. IMPORTANT SPACES SHOULD BE INDICATED BY A ∧
If the space symbol ∧ itself is to be typed, indicate this by an instruction to the typist. ]f a specific number of spaces is required, then make it clear. For example, with a sample piece of FORTRAN, the figure 6 circled can be written where typing would normally begin, to indicate that 6 spaces should be left. It is difficult for the typist to know when she needs to be precise, so do not leave a long gap between words or symbols where there should be only one space, or no spaces at all.
5. MAKE SURE THE TYPIST CAN DIFFERENTIATE BETWEEN O AND o
The digit 0 can be emphasized by writing with a stroke through it. The letter O can be emphasized.by writing as O with a bar over it. Putting a slash through the zero is preferred. If the slash needs to be typed, indicate this by an instruction to the typist.
6 INDICATE FOOTNOTES BY A DAGGER SIGN
Asterisks should not be used as they are part of the 1900 character set.
7. WORDS REQUIRED IN ITALICS SHOULD HAVE WAVY UNDERLINING
8. SYSTEM NAMES SHOULD BE IN UPPER CASE
Names of compilers, parameters and subsystems should be written in upper case. For example:
MOP GEORGE EXECUTIVE FORTRAN ALGOL SPROGS
9. "FOR EXAMPLE" SHOULD BE FOLLOWED BY :
When writing "for example", "the following", "given below" and similar such phrases, which precedes several lines of text, we have decided to standardise on a colon to follow these (for example:) rather than to use a :- or just - . I prefer "for example" to be written out in full rather than using "eg ".
FOR MANUALS
10. CHAPTER HEADINGS SHOULD BE IN UPPER CASE
11. SECTION HEADINGS SHOULD BE UNDERLINED AND UPPER AND LOWER CASE
For example 
An example is:
10. THE CHAPTER HEADING (this can be centred)
10.1 This is a Section (underlined_
12. NEVER REFER TO PAGE NUMBERS
Always refer to Chapter 5 or Section 5.5. Page numbers will almost certainly be changed in a later edition of a manual.
13. KEEP SECTIONS SHORT
Sections should not normally be longer than a page or two - this means that on opening a manual at any page, there is nearly always an indication of which chapter the reader is at.
14. SUB-SECTIONS SHOULD BE AVOIDED IF POSSIBLE
Sub-sections such as 5.5.1 and 5.5.5.1 should be avoided if possible. It is preferable to use (a), (b) etc or (1) (2) etc. Note these should have double brackets and nt a) and 1).
15. DO NOT WRITE IN FIRST PERSON
Keep to the third person, or subject - "The system will be re-written" rather than "I will re-write the system". "You can rewrite the tape" can be replaced by "The tape can be rewound" or "One can rewind the tape".
16. AVOID "CONVERSATIONAL" WORDS
Do not use "don't", "wouldn't", "he'll" etc in writen English.

FINALLY BE CONSISTENT

NOTE: When a typed copy is returned to you for checking, you can mark any corrections required in ink. Place an X in the margin opposite the line on which a correction is necessary and either mark the correction in the text, if there is room, or write it in the margin. Standard Printers' correction marks are not required.

⇑ Top of page
© Chilton Computing and UKRI Science and Technology Facilities Council webmaster@chilton-computing.org.uk
Our thanks to UKRI Science and Technology Facilities Council for hosting this site