ML20207S867
| ML20207S867 | |
| Person / Time | |
|---|---|
| Issue date: | 03/06/1987 |
| From: | Seelig C NRC OFFICE OF NUCLEAR MATERIAL SAFETY & SAFEGUARDS (NMSS) |
| To: | Vanduser K NRC OFFICE OF INFORMATION RESOURCES MANAGEMENT (IRM) |
| References | |
| REF-WM-1 NUDOCS 8703200347 | |
| Download: ML20207S867 (5) | |
Text
^
W 4
2.12.1/CS/87/03/04 NAR 0 6MOCKET CONTROL CENTER MEMORANDUM FORT Karen M. VanDuser, Acting Chief 87 NAR 13 AH :03 Information Technology Services Branch Division of Information Support Services Office of Information Resources Management FROM:
Claudia A. Seelig, Acting Assistant Director Planning and Program Analysis Staff Office of Nuclear Material Safety and Safeguards
SUBJECT:
DRAFT MICROCOMPUTER APPLICATIONS SOFTWARE DOCUMENTATION STANDARDS In response to your February 5 request, NHSS has reviewed the draft standards.
The technical content of the document is quite good.
The examples appear to be carefully thought out and relevant.
However, we do offer the enclosed comments.
If you have any questions, please call me on ext. 74072.
c4o Claudia A. Seelig, Acting Assistant Director Planning and Program Analysis Staff Office of Nuclear Material Safety and Safeguards
Enclosure:
As stated Distribution:
WM Poicct ___L-gg ggg g.3 P B 2.12.1 f
,_j,gff_,
Dodet (b. -
y
'CSeelig e ggg _ _
DW&n_
f^Og/s4 d_ e_,-r~ ~l'._ -
[LiWn E W3,623 W 8703200347 B70306 PDR WASTE WM-1 PDR OFC :NMSS:PPAS
.........q.y..__...................__......................__...............................
NAME :CIslalig:aw DATE :3/(c/87
[
't NMSS COMENTS ON MICROCOMPUTER APPLICATIONS SOFTWARE DOCUMENTATION STANDARDS, OCTOBER 1986 1.
The " Documentation Requirements" section on page 2 is confusing and should be replaced with a reference to the documentation requirements specified in NRC Bulletin 0904-3, which state that documentation is mandatory for all organization-unique use and corporate use applications and good prac-tice for individual use applications.
2.
The document should recognize and, where appropriate, rely upon other software documentation standards.
Some examples are:
NRC Regulations - 10 CFR 50, Appendix B, Part V (Instructions, Procedures, and Drawings); 10 CFR 50, Appendix K, Part II (Required Documentation).
NRC Documents - NUREG-0856 (Final Technical Position on Documentation of Computer Codes for High-Level Waste Management), June 1983.
Other Agency Standards - Federal Information Processing Standards Publication Number 38 (Guidelines for Documentation of Computer Programs and Automated Data Systems), 15 February 1976; FIPS PUB 64 (Guidelines for a
Documentation of Computer Programs and Automated Data Systems for the Initiation Phase),1 August 1979; FIPS PUB 105 (Guideline for Software Documentation Management), 6 June 1984; NBS Special Publication 500-73 (Computer Model Documentation Guide), January 1981.
3.
Regarding item 1 on page 1: Although commenting inside source code is desirable, it is not always practical with large programs.
This is pri-marily due to limitations on the size of the file that can be accommodated by the available editors or on the maximum allowed size of the code seg-ment.
BASIC programs and data combined are limited to about 60Kb and the dBaseIII+ built-in word processor can handle only about SKb.
There are always limitations for programming environments on personal corputers, and end-user programmers invariably bump up against them--either for lack of expertise or an oversupply of ambition.
However, some of these limita-tions are more confining and unpecessary than others.
The problem can be alleviated in dBaseIII+ by making available for use in the agency ASCII text editors capable of handling larger size files.
For example, PCWrite used as a program editor can handle files as large as 64Kb.
In some cases, even this size limitation becomes critical, and a special purpose program editor may become necessary. (Program size limitations may also be worked around by breaking up programs into a number of smaller 1
e
~
I 2.12.1/CS/87/03/04 2
modules which are called from a main program when needed.
However, this makes the overall program slower to execute because each file must be loaded into memory from the disk before it can be executed.)
Size limitations in BASIC might be alleviated by using a BASIC compiler for which the source code may not be limited in size, although the code segment may still be Ifmited.
Compilers may also be useful in this regard for dBaseIII+.
In view of these size limitations, the draft standard should indicate that sufficient space for commenting could be made available for large files through the use of an alternat.ive editor or programming environment (assum-ing the agency is willin!) tc make such alternatives available).
If the agency wants to conduct a test of several program editors which allow larger file sizes, NMSS is available to participate.
4.
Systems Level Documentation (p. 4).
The requirement for including systems level documentation appears to be redundant.
It appears that whenever any documentation is required, it must include systems level documentation.
Thus, the conditions listed are conditions for all documentation, not just for the systems level component.
A clearer approach would be to replace the criteria at the top of page 4 with the following:
Systems level documentation is always required whenever documentation of an application is required.
In addition, however, other components of a complete documentation package may be required, depending on the type of application, as detailed in Chapters 2 through 8.
In addition, the parenthetical remark in item b. is unnecessarily confin-ing since flowcharts may easily be maintained on a word processor or other software which has line drawing capability, as well as by hand.
- Also, rather than continually repeat the requirement to use a word processor for maintenance, it would be more succinct to include just a single statement that, "... all aspects of the systems level documentation, except possibly the flowchart, should be maintained using a word processor."
l Instead of providing " flowcharts," one should have an option of providing a pseudocode listing such as the following:
I get old dose j
get new dose if old > new, go to recalculate program if old < new, print new dose etc.
J(
2.12.1/CS/87/03/04 3
Finally, the term " flowcharting paper" is not meaningful and should simply be shortened to " paper."
5.
Contents of System Level Documentation (pp. 5-8).
The description of the File Summary (p. 6) indicates that this should more aptly be named the Data File Summary, since it is. supposed to contain information only about data files.
The contents of the User's Guide (p. 6, item 2.c) includes information about the hardware and software requirements of the application that seems to be redundant with the Microcomputer System Summary (p. 5, item 4) that is supposed to also be part of.the documentation.
It is stated (p. 7, item 4) that there are three required appendices, but there are four described below this statement (pp. 7,8).
The requirement for a list of error messages (p. 7) should be clarified to specify that DOS error messages and those generated by the commercial soft-ware need not be included, since these are generally documented by the soft-ware vendor.
There is a requirement under Problem Resolution (p. 8) for identifying a contact (s) for the user who experiences difficulty with the application.
This contact is supposed to be re.,ponsible for maintaining the application.
It should be stipulated that such a contact need not be considered a resource for other users outside the organizational unit (s) which support the application unless appropriate arangements have been made between the affected management units for such a sharing of resources.
The requirement for a Change Log (p. 8) should be clarified to reflect that the change log is not started until the program / system is " operational."
Where it states that other appendices should be included as appropriate, either criteria should be provided for determining what is appropriate or the wording should be changed to, "may be included as appropriate."
6.
bocumentation Requirements for dBaseIII (pp. 9-21).
In order to reduce the chances of end-users providing inaccurate documentation, thus wasting effort and misleading other users who may wish to make use of the documun-tation, it is suggested that the development of the Data Dictionary for dBaseIII be automated as much as possible.
Commercial products, such as dutil, produced by Fox &Geller, perform this function automatically and with little chance for error.
Similarly, system flowcharts also should ha drafted automatically.
This is a function that dutil also may be dole to perform.
If commercial software is not available, then it may be f easible to develop such a program in-house, considering the amount of staff time
5 I
2.12.1/CS/87/03/04 4
that may be saved by such a program.
Lotus's new macro-manager, Metro, may also be of use in automating documentation for spreadsheets.
Similar approaches could be pursued for other types of applications, such as BASIC or FORTRAN.
The data dictionary appears to contain all the information contained in the file layouts (p. 10), thus making them unnecessary (especially since they could always be generated by anyone with access to the files).
7.
Lotus 1-2-3 Documentation Requirements (pp. 17-21).
Somewhere, either in this chapter, or in Chapter 1, it may be useful to insert a reminder to mention whether the hardware configuration contains a math coprocessor chip.
8.
General Remarks.
For a large application in BASIC, it is highly likely that the environment of choice would be in a compiled BASIC.
Some BASIC compilers already exist in the agency, and new releases of Microsoft's Quick 8asic 2.0 and Borland's Turbo-Basic make using the old interpreter BASIC outmoded and wasteful of valuable resources for any significant applications in BASIC.
The draft documentation requirements therefore would be incomplete if some reference were not made to the use of BASIC compilers (other than simply referring to source code).
One important concern for any compiled language applica-tion, which may not always be obvious to inexperienced users, would be that end-users using a compiler should always preserve the source code used to generate the compiled application, and that the source code should contain the required comments.
The word " compliment" is systematically misused in place of the word
" complement."
ITS microcomputer training course agendas should cover documentation requirements.
It may be useful to hand out documentation of the sample programs used in these courses.
e e