HARDWARE DOCUMENTATION STANDARDS L. D'Addario 94/12/07 The hardware of the Green Bank OVLBI Earth Station is being documented at several levels. These are described here for reference. Software documentation is not considered here; it is a separate matter. The documentation types are: Distributed memos; Design documents (undistributed); Drawings; Parts lists (Bills of Materials) and parts data base; and Manuals. 1. DISTRIBUTED MEMOS These are the numbered memos of the OVLBI-ES series. They generally cover design issues that were considered before implementation, and represent the INTENDED design. The memos are informal and are not refereed. Some are obsolete (although their status as current or obsolete should be indicated in their index file). Therefore, the memos should be relied upon mainly for background and support, not as a definitive description of the design. 2. UNDISTRIBUTED DESIGN DOCUMENTS These are precise statements of design decisions that are maintained as computer files (ASCII or TeX) and are kept under sccs control. They should be up to date. Very few documents of this type exist at the moment (except for software). 3. DRAWINGS Nearly all electronic and mechanical hardware is described in drawings. These are intended to be precise and definitive, and should always be up to date. With rare exceptions, all drawings are required to be computer generated, using either AUTOCAD (for mechanical drawings) or OrCAD (for electrical schematics, block diagrams, etc.). In the future other software packages may be acceptable, but for now only these are supported. Preliminary drawings may exist only on paper, but they must still be numbered and indexed and a plan should exist for converting each to computer form. The engineer responsible for each module or subsystem that has been specially designed for this project needs to submit a set of drawings sufficiently complete to allow that hardware to be re-constructed. Every drawing must have a number of the form pppppTxxx[R] where 3.1 ppppp is the 5-digit Project Number associated with the subsystem to which the drawing applies; 3.2 T is the drawing type code (see [1]); 3.3 xxx is a 3-digit sequence number, starting with 001 and incrementing for each drawing for which the first 6 characters of the number are the same; and 3.4 R is a revision letter; it is null for the initial version, A for the first revision, B for the second, etc. The number may also have an optional prefix letter to indicate the natural size of paper copies (A, B, ...) of the drawing. Drawing numbers are centrally maintained and assigned. At present the master list is on paper in a looseleaf notebook in the project office, but it will soon be made into a computer file with very limited write permission but wide read permission. A master drawing archive will be maintained on the Unix file server in Green Bank, with files stored in the native format of the program used to generate them. The drawing files will have wide read permission but limited write permission. Responsibility for maintenance of the archive belongs to the OVLBI project manager, but eventually it will be transferred to the Green Bank Operations drafting office. Details are given in [2]. 4. PART LISTS AND PARTS DATA BASE Every item making up the entire station is assigned a part number. These can be understood as forming a hierarchical structure that separates them into three types: 4.1 Elementary parts that are not further broken down. These include any item ordered from an outside vendor and any item fabricated at NRAO from general purpose, basic materials that are normally kept in stock. 4.2 Assemblies that are made up of elementary parts or of lower-level assemblies. All of these are considered to be manufactured by NRAO, even if they are just assembled from purchased parts. In a few cases, some judgement is needed in deciding whether something is an elementary part or an assembly; e.g., a box consisting of a few shop-fabricated metal parts plus some standard hardware could be considered an elementary part, but it should be considered an assembly if there is any reasonable need to keep track of its components. 4.3 The one top-level assembly that is the entire Earth Station. Except for the last item, each part has an assembly to which it belongs. The list of parts making up that assembly is its Bill of Materials (BOM), and this is an important element of the station documentation. To facilitate the generation of BOMs, a master data base of all parts is being established. The details of this are given in [3]. Each designer who is responsible for a module or subsystem will need to supply a complete parts list in the form of a data base having the specified structure; this will be merged into the master data base. In principle, every assembly is described by an Assembly Drawing (drawing type "A") which shows the physical relationship of all component parts. A BOM is also considered a "drawing" (type "B"). There is thus a pair of drawings, Assembly and BOM, associated with each assembly. The part number is always the same as the Assembly drawing number. In practice, the actual Assembly Drawing may not always be created, but a part number and hence an assembly drawing number must always be assigned. For elementary parts that are fabricated by NRAO, the part number is the same as the number of the drawing that shows how to make it. Usually this is a mechanical drawing (type "M"). If several parts are shown on the same drawing, then a "dash number" is appended to the drawing number to distinguish the part (e.g., part number 34223M002-3 is item 3 of drawing 34223M002). For purchased parts, the part number is the one given to it by its manufacturer. The hierarchical breakdown of the station into assemblies is somewhat arbitrary. At the first level, a list of the assemblies that make up the whole station will be created by the project manager. Beyond that, the engineer responsible for each first-level assembly will decide how many levels of breakdown are reasonable. The following is provided as general guidance. Each plug-in electronic module is a first-level assembly, as is the rack into which the module is installed. Anything that can be removed and tested separately (like a printed circuit board or a small electronic box), or that is duplicated in its entirety and used in more than one place, should normally be treated as an assembly. It is usually convenient if things that are documented on separate drawings are treated as assemblies. Eventually, it should be possible to generate very complete BOMs for every assembly at every level, including just about every nut or bolt and every piece of wire. But this will be difficult in the beginning, so partial or incomplete BOMs are entirely acceptable. It is much better to have an incomplete BOM than none at all, and the parts that were forgotten at first can always be added later. Nevertheless, an effort should be made to make the BOMs as complete as possible. 5. MANUALS Every module, major assembly, or subsystem that has been specially constructed for this project will be documented in a Manual. A Manual is a spiral-bound booklet that gives a complete, "as built" description of the subject hardware, along with instructions for its maintenance. The minimum content of a manual is: 5.1 Design overview. This is a general description of the device, including its purpose and function in the overall scheme of the station. The design principles should be discussed here, along with the reasons for rejecting alternative designs, if appropriate. If this information was already included in a distributed memo which is up to date or in a design document, then it is appropriate to include that document as an appendix to the manual and to reference it here; in that case, this section could be rather short. 5.2 Performance specifications. Precise data should be given, in as much detail as possible. The objective is to allow someone else to verify whether the device is later working properly or not. 5.3 Detailed description. This should explain the purpose and operation of each part to the extent that it would not be obvious to a well trained technician. It should be at a level that is appropriate to someone new to the equipment who is generally familiar with the type of parts used, but who does not know anything about this design. 5.4 Maintenance procedures. This should include any procedures for disassembly and replacement of parts that would not be obvious to a well trained technician. It must include procedures for any adjustments that are needed to achieve the specifications, and for any tests that are needed to verify proper performance. 5.5 Interface data. This includes pinouts of all external connectors; levels and logical meanings of all external signals; and complete syntax and semantics of all computer commands and monitor data, if applicable. 5.6 Drawing number list. This includes numbers and titles of all drawings, including all types, that are associated with the subject hardware. Those drawings that are needed to understand the operation of the device (as opposed to those needed to construct another one) should be reproduced in the manual. 5.7 BOM listings. Printouts of BOMs at all levels should be included in an appendix, unless they would be unreasonably voluminous. In the latter case, an explanation of how to generate or find the BOM should be given. 5.8 Data sheets of purchased parts. Except for generic parts whose long-term availability is reasonably assured, manufacturer's data sheets on the parts actually purchased when the device was built should be reproduced in an appendix. 5.9 References. All other documents related to the subject hardware, including our distributed memos, our design documents, papers published in journals, and earlier work at NRAO or elsewhere on similar devices, should be referenced. Each reference should include enough information so that someone inside NRAO can easily find a copy of the document. REFERENCES [1] H. Dill, "Drawing Numbers." VLBA-CC Memo No. 23, 840112. Should be in all NRAO libraries. [2] L. D'Addario, "OVLBI Earth Station Parts Data Base." File ftp.gb.nrao.edu:ovlbi/doc/parts-database.doc. Version 1.1, 94/12/07. [3] L. D'Addario, "OVLBI Drawing Archives." File ftp.gb.nrao.edu:ovlbi/doc/drawings.doc. Version 1.1, 94/12/05.