include carefully selected examples, to illustrate the functions and their most important variations (these will be useful later as test cases). The lowest level of the hierarchy is the program text itself.
This way of work not only has the advantage that important parts of the documentation are actually produced. It also leads to better programs. In fact, when working out the higher level descriptions in written form, the software producer inevitably will be forced to think out his data and program structures more carefully than otherwise. This regularly leads to programs with clearer structure, higher efficiency, and fewer bugs.
This way of developing the software and its documentation also allows for mutual review, check, and criticism within small groups of software programmers. This should take place frequently while the work is in progress and can very well be done within groups of two people who look into another’s work. In my experience this is a highly effective way of organizing the software work.«
David: One has to avoid flooding people with so much information that they ignore it all. Selective dissemination of information, by means of a system such as Mercury (see W.S. Brown, J.R. Pierce, J.F. Traub: The Future of Scientific Journals, Science, December 7967) at Bell Laboratories should be tried in a large software project.
Randell: It is relatively easy to set up a communication system, manual or automatic, which will let me find information that I already realise I need to know. It is more difficult to make sure I also get information which I need, but of whose very existence I am ignorant.
Finally, several people gave interesting case histories of the methods used for internal communication within a production team.
Opler: I think I know how to organise reasonably successful communication for projects of between 10 and 50 people. I am quite sure I don’t know how to do it with projects of much greater size. The method we used was as follows. From the moment the project is created every member of the staff receives a three-ring binder and perhaps half-a-dozen pages stating the very first decisions and ground rules for the project, including an index. As the project proceeds everybody contributes sheets, which must be countersigned by their management. As the project grows so does the notebook. Hopefully the document classification system remains adequate. We had at most a one-day delay between origination of a document and distribution to all members of the group. This had interesting side-effects. I noticed that one part of the book was not filling in very fast — this led to early discovery of a worker who was lagging behind, and who eventually had to be dismissed.
Fraser: The question of what methods should be used for organising information flow between members of a production team depends largely on the size of the team. I was associated with a 30-man project, producing a commercial compiler (NEBULA) for the I.C.T. ORION Computer. We had three, or rather four, forms of information flow. The first was based on the fact that the compiler was written in a high-level language and hence provided, in part, its own documentation. The second form of information flow was based on documentation kept in a random access device which was regularly accessed by every member of the team. This was a steel filing cabinet kept in my office. It contained files consisting of scruffy bits of paper with various notes and messages from one member of the team to another. This was probably the most important form of communication we had. Its merits were that there was only one set of authoritative information, and that the indexing scheme, albeit crude, was sufficient to allow one to find, in most cases, the relevant information when you needed to make a decision. I don’t see any advantage in automating such a system for a group of 30 men. A filing cabinet is easy to use, and there were not many occasions when there were long queues outside my office.
The other filing system we had was an automated text-handling system, in which we kept the official project documentation. This was not much use for day-to-day communication, but invaluable for program maintenance and also program revision in the light of further developments. There was a fourth communications mechanism which every project has, and which perhaps doesn’t get encouraged as much as it should be. There are certain people in any organization who are remarkably effective at passing gossip. Many of the potential troubles in a system can be brought into the open, or even solved, by encouraging a bit of gossip.
Nash: I would like to report on documentation of the F-level PL/1 compiler, where we had a team of about two dozen people on the actual development. We did not have any private memos, or notes, although we had a considerable amount of verbal communication. What we did establish was a book which described in complete detail every