Define Version Controls and Software Documentation

Version Controls

Library controls facilitate software version controls. Version controls provide a means to systematically retain chronological copies of revised programs and program documentation.

Development version control systems sometimes referred to as concurrent version systems, assist organizations in tracking different versions of source code during development. The systems do not simply identify and store multiple versions of source code files. They maintain one file and identify and store only changed code. When a user requests a particular version, the system recreates that version. Concurrent version systems facilitate quick identification of programming errors. For example, if programmers install a revised program on a test server and discover programming errors, they only have to review the changed code to identify the error.

Software Documentation

Organizations should maintain detailed documentation for each application and application system in production. Thorough documentation enhances an organization’s ability to understand functional, security, and control features and improves its ability to use and maintain the software. The documentation should contain detailed application descriptions, programming documentation, and operating instructions. Standards should be in place that identify the type and format of required documentation such as system narratives, flowcharts, and any special system coding, internal controls, or file layouts not identified within individual application documentation.

Management should maintain documentation for internally developed programs and externally acquired products. In the case of acquired software, management should ensure (either through an internal review or third-party certification) prior to purchase, that an acquired product’s documentation meets their organization’s minimum documentation standards. For additional information regarding acquired software distinctions (open/closed code) refer to the “Escrowed Documentation” discussion in the “Acquisition” section.

Examiners should consider access and change controls when assessing documentation activities. Change controls help ensure organizations appropriately approve, test, and record software modifications. Access controls help ensure individuals only have access to sections of documentation directly related to their job functions.

System documentation should include

System Descriptions

System descriptions provide narrative explanations of operating environments and the interrelated input, processing, and output functions of integrated application systems.

System Documentation

System documentation includes system flowcharts and models that identify the source and type of input information, processing and control actions (automated and manual), and the nature and location of output information.

System File Layouts

System file layouts describe collections of related records generated by individual processing applications. For example, personnel may need system file layouts to describe interim files, such as sorted deposit transaction files, in order to further define master file processing requirements.

Application Documentation Should Include

Application Descriptions

Application descriptions provide narrative explanations of the purpose of an application and provide overviews of data input, processing, and output functions.

Layouts

Layouts represent the format of stored and displayed information such as database layouts, screen displays, and hardcopy information.

Program Documentation

Program documentation details specific data input, processing, and output instructions, and should include documentation on system security. Program listings/ source code and related narrative comments are the most basic items in program documentation and consist of technical programming scripts and non-technical descriptions of the scripts. It is important that developers update the listings and comment documentation when they modify programs. Many software development tools are available that automatically create source listings and narrative descriptions.

Traditionally, designers and developers have used flowcharts to present pictorial views of the sequencing of procedural programs such as COBOL and Assembler. Flowcharts provide a practical way to illustrate complex programs and routines. Flowcharting software is available that can automatically chart programs or enable programmers to chart programs dynamically without the need to draw them manually. Programming techniques, such as object-oriented programming, have contributed to the use of dynamic flowcharting products. Maintaining detailed documentation of object-oriented code is particularly important because a primary benefit of the programming technique is the reuse of program objects.

Naming Conventions

Naming conventions are a critical part of program documentation. Software pro-grams are comprised of many lines of code, usually arranged hierarchically into small groups of code (modules, subroutines, or components), that perform individual func-tions within an application. Programmers should name and document the modules and any related subroutines, databases, or programs that interact with an application. Stand-ardized naming conventions allow programmers to link subroutines into a unified pro-gram efficiently and facilitate technicians’ and programmers’ ability to understand and modify programs.

Operator Instructions

Organizations should establish operator instructions regarding all processing applications. The guidance should explain how to perform particular jobs, including how operators should respond to system requests or interrupts. The documentation should only include information pertinent to the computer operator’s function. Program documentation such as source listings, record layouts, and program flowcharts should not be accessible to an operator. Operator instructions should be thorough enough to permit an experienced operator who is unfamiliar with the application to run a program successfully without assistance.

End-User Instructions

Organizations should establish end-user instructions that describe how to use an application. Operation manuals, online help features, and system error messages are forms of instructions that assist individuals in using applications and responding to problems.