We’re always striving to find new ways for community members to share knowledge with one another. In Parts 1 & 2 of Mike Malesevich’s posts on system documentation, he has compiled lists of what your system documentation should include, and what the process should look like. That’s where you come in: We want to hear from you about your own processes of system documentation. Share with us what it looks like, what your obstacles are, and what you’ve found works for you. Leave this information in the comments section so we can soon compile it into a living wiki for everyone to access. Have questions? Let me know at Melanie@ITKnowledgeExchange.com. Read 5 Things Your System Documentation Should Be – Part 1.
Get in on the discussion in our Open IT Forum.
I have suggested five components of an application documentation set. This configuration provides a structured organization, covers a wide range of clients, and minimizes overlap. Not every application will require all the components.
Now, I will describe the components in more detail.
The Overview component is your marketing pitch. It describes your product in high-level detail, identifies key application elements and tells your prospective customers why this product is the best one for them. I once was responsible for maintaining a large banking application and fortunately, the overview documentation provided me with information which made the task less terrifying. It described the various time dependent functions (daily, weekly, monthly, year-end, backups, etc.), inputs and outputs.
Think of this as the glossy brochure you read before beginning your search for a new automobile. It quickly will identify key features of the automobile which you can then compare with your needs.
The Operational component is your will and testament. It states how the application is to be managed after you (or your team) are gone. The ideal goal is to turn over the day-to-day operation of the application to another group without your close involvement. This information can be enhanced over time. I used this vehicle to document application issues and resolutions. If changes to the system were required, this was also noted. If the application crashed, there should be documentation for attempting a resolution (or only call the on-duty support staff), perhaps manually resetting control items (dates, cycle numbers, cheque numbers, etc.), voiding/deleting output information (such as files, cheques, etc.) or rerunning the application. This last option could entail manual over-rides to input and output files, reports, etc. As issues arise over time, the documented resolutions may help resolve late night issues.
This documentation should also describe the relationship of data files and the various application components. As and example, the daily function might consist of enabling the online files by 5:00 AM and initializing the log files. The nightly function could state that the online component is to be stopped by 9:00 PM, the backups to be completed by 11:00 PM and sent off-site, the aging function to be completed by 2:00 AM, the verification function to be completed by 3:00 AM, all client reports/information to be processed and distributed by 6:30 AM. As stated earlier, any operational issues should be documented in this component.
The Programmer component is probably the heart of this documentation. It contains not only the code for the applications, scripts, tables, etc. but also the modification history of the application. It shows approved changes, what components were changed for each revision, and if you’re lucky, it might even provide a backout solution. This is the bible for application support staff.
The Customer component is the ‘how to’ resource for the users of the application, and tells them how to use the application in the most effective manner. It should be created by function (how to create a data record, how to delete a record, how to modify a data record, how to select data for reports, how to manage various control elements, etc.). This document should be written with the client in mind – how will they use the system. There are several formats that can be used, and I am fan of a 3 column tabular version. The 3 columns contain a sequence number, an action column and a results column. The integer sequence number indicates the function (such as the login process is 1.0), The action column indicates what the client must do to achieve the result or what the function is, and the results column describes what will occur.
I personally don’t like the SELECT, CLICK, CLICK, etc. approach, because the client may not fully understand the process, they just follow the rules. Another technique, which initially is nice, is to use screen images to instruct clients. This is valid until a change to the graphical interface is made, thus possibly making the documentation confusing or incorrect. The documentation should be designed to minimize revisions when modifications are made to the application.
The following attempts to illustrate a login scenario:
STEP ACTION RESULT
1.0 LOGIN
1.1 Select APP, Press ENTER Invokes login screen from standard corporate menu
Go to STEP 1.3
1.2 Press: CNTL+ALT+PGDN This invokes the stand alone login screen
1.3 Login screen appears
1.3.1 Enter your account id This is your id for this application
1.3.2 TAB to password field
1.3.3 Enter your account password Field contents not displayed
1.3.4 Press ENTER key Valid account/password invokes APP
1.3.4.1 Invalid password prompts for another attempt
1.3.4.2 Go to 1.3.1 After 5 invalid attempts, account is suspended for 1 hour
1.3.4.3 Contact HELP desk Account activation
The Data Dictionary is the hub that holds these components together. Unfortunately, I have not found a product that works to my satisfaction. This repository should contain the data elements for the all applications, along with definitions, formats, edit/verification rules, etc. There would be links identifying the applications, data files, data bases, etc. using the elements. This would help ensure that the data elements are used correctly. The data elements could have alias names which could be used by different programming languages. Just think how easier application support would be if every program used the same set of data element names?
I have worked on several projects where the data elements were defined before the source code was developed. It took a while to get the data elements correct (you don’t need to be 100% complete), but the programs were developed much faster and with fewer errors. In one project, we developed month-end profit ratios for manufacturing plants. There were over 200 reports and each program used the common data element definitions. It is now relatively easy to trace data elements to programs, files, reports, and data bases. All system clients use the same terminology, know the data element definitions and what they represent – thus avoiding some misunderstandings.
This documentation model is not perfect. I feel it can be used as a basis to develop better documentation. After all, if you have a problem with an application, where do you turn to for help? If the documentation is poor, no matter how wonderful the application, it is bound to fail. Just like the chain, it is as strong as the weakest link.
Mike Malesevich has been an IT professional for over 30 years, working with IBM mainframes and UNIX. From application developer, tech support to operations support analyst and security admin, Malesevich has made his rounds in information technology.
