The level of funding justified and made available for development is not extended to maintaining many of the systems or their documentation once they are migrated into production.
This level of documentation may be warranted on mission-critical projects such as software for man–space travel. In most instances, it is sheer overkill and can actually impede the development effort by forcing focus on documentation deliverables while coding and testing time are diminished.
SYSTEM DEVELOPMENT — WHAT IS RIGHT
The integration of systems and the expansion of internal systems to communicate with external systems dictates that some consistency in the varying approaches needs to be established. Methodologies attempting to fill this need have sprung up everywhere. Browsing through any computer science section of Amazon.com, Borders, or Barnes & Noble will reveal book after book on the approaches that can be used. Government contractors hoping to secure work in the private sector as budgets of many agencies are cut, are coming forward declaring that they have the answers.
They bring with them approaches developed for full-scale, complex efforts that are
overkill for commercial systems development. The benefits of tools such as the International Standards Organization (ISO) quality standards, series 9000, and the Software Engineering Institute’
s Capability Maturity Model (SEI CMM) are expensive
to realize if the tools are not adequately tailored. For some profit-based companies, funding for the use of these tools is nearly impossible.
Efforts are being made throughout the computer industry to find some common ground for the approach to software development. Industry leaders are standardizing interfaces to increase application portability, broadening the need for companies to know how their systems work. The point of all of this is perhaps viewed as reference material in much the same way as an encyclopedia. Use the information to get smarter and then apply the information with common sense. Keep in mind that some very smart people can be very good at telling others how to do things, but lack the ability and know-how to get the job done. People who have been in the trenches on small and large projects know and understand that there is a happy median that can and must be achieved.
Get the Basics
At a minimum, a description of each application, existing and planned, needs to be written down and maintained. Whether the application is a stand-alone database that allows queries to be made using a variety of personal computer products or code that will convert a legacy system to the latest and greatest technology, it is critical to know what is going on in development. A good description of an application will include the following information.
§ Application purpose statement
§ Input and output requirements
§ Hardware requirements
§ Software environment requirements
§ Location of current version of source code or COTS installed
§ Version/last modified descriptions
With this information, all else can be reconstructed on an as-needed basis.
Application Purpose Statement The application purpose statement tells the business reason for having the software, the limitations and capabilities of the product, and the point of contact for getting questions answered about the product.
This is a nontechnical statement that explains what the application is and what it does. It is written at the application component level rather than system component level. For example, a financial system will in all probability include applications for general ledger, journal processing, and accounts payable. A purpose statement is written for general ledger, journal processing, and accounts payable. They can then be bound in one document but each needs to be clearly described independently of the others because they will be maintained and upgraded individually over time.
The purpose statement needs to be text. Diagrams are nice, but are only supportive to the text because diagrams generally cannot contain all of the necessary information without becoming too complex to read.
Input and Output Requirements It is essential to know what data is expected by the application and what data is generated by the application. When an application expects data, it is going to come from one of three sources: a file input, a program process, or a user. That information needs to be stated. If the application gets the information from a file or outside database, the file name and database tables need to be identified. When the application gets the information from a process within the program logic, the logic needs to be described. When the application gets the information from a user, valid values and ranges must be documented.
When an application generates data, it is going to either send it somewhere or keep it. If the application is sending the data somewhere, the target file name and database table need to be given. If it is going to display the data, this needs to be explained. If the application only stores the data within the application to be used for queries and reports, rules governing update rotations, archiving, and purging need to be provided.
The input/output information is best presented in a table format. The data items can be listed alphabetically, making it easy to find the data path for application maintenance and troubleshooting.
Hardware Requirements This should be a very basic list of what equipment is needed in order for the application to run in any organization. The list should give the minimum requirements for processor capability and memory.
Software Environment Requirements This list needs to specify any software components needed on the system in order to run the application. This includes the operating system release and version, database release and version, and any other applications the application being described needs.
Location of Current Version of Source and Object Code or COTS Installed This piece of documentation becomes essential in maintaining the integrity in the development environment. The best way to have this information available and accurate is to use configuration management tools.
Version/Last Modified Descriptions This piece of documentation specifically states what changes have been made to the application and when they were made.
Additional information about who made the changes can be of value only if the coding organization is static. The “who did it” factor becomes meaningless in dynamic organizations.
It is best to have individual version reports for each release, rather than continuing lists of changes. This approach promotes more thorough documentation.
SYSTEMS DEVELOPMENT — IS THAT IT?
Having the basic documentation enables a company to build any additional documentation that may be planned. In the government world, it can be used to generate as much paper as the project demands. In a commercial product development world, it provides sufficient information for technical writers to generate operations and user manuals. In IT departments, it ensures that code is managed and can be upgraded, converted, and used in constructive and productive ways.
Within each organization, there needs to be a standardized format for the basic documentation. Peer and management reviews of the basic documentation should be included in the development schedule. The reviews may be conducted as formal meetings where everyone gathers in a room and goes through the documentation page by page, or as informal reviews where the document is distributed and comments are submitted to the authoring team. Procedures for maintaining and updating the electronic and hardcopy versions of the documentation must exist.
SYSTEMS DEVELOPMENT SUMMARY
Using a checklist as shown in Exhibit 1 can help to get things started. The point is that basic documentation imposes order on every development effort. Increased order allows for more thorough and consistent management of development processes. More thorough and consistent management results in more realistic schedules and staffing for future development work, whether it is new application development, legacy system conversions, maintenance work, or additional types of documentation for the marketplace.
Exhibit 1. Basic Documentation Checklist
Item Category
Items
Status
No.
1.
Application
Business reason for application
purpose statement Limitations and capabilities
Point of contact
Exaplanation of application components and
what they do
2.
Input and output Database tables used by application
requirements
Files used by application
Internal interfaces
Sending application with file names sent
External interfaces
Sending system with file names sent
3.
Hardware
Processor
requirements
Disk space
Memory
Printer name
4.
Software
Operating system
requirements
Database
Item Category
Items
Status
No.
Send to interface applications
Receive from interface applications
5.
Location of code
Name of machine
and COTS
Name of directory
Name of files
6.
Version
Name of application
descriptions
Name of each program changed
Recompile complete
Description of changes made for each of the
programs
Name of database table change
Description of changes made to each table
Establishing a practice of basic documentation provides ancillary benefits in that contract employees can be brought up to speed faster and their work can be checked and managed better. New technology can be adopted into environments more readily. Short- and long-term planning and bids for funding can be developed more meaningfully and documented more completely. In all, just sticking with the basics creates a win–win situation for everyone fro m management, to developers, to users.