Enterprise IT Watch Blog

Aug 29 2011   8:36AM GMT

5 Things Your System Documentation Should Be – Part 2

Guest Author Profile: Guest Author

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:


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 Invalid password prompts for another attempt Go to 1.3.1 After 5 invalid attempts, account is suspended for 1 hour 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.

3  Comments on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.
  • LinuxCiscoman
    In my opinion, as a networking professional, proper documentation is the absolute, most necessary part of any technology implementation. In my opinion, a good project is one that does not need repair but maintenance. However, as Mr. Malesevich so aptly stated earlier, this is simply non existent in our disorderly and chaotic world. The reality of the matter is that things do break and although some would argue, System and Network Admins are not God's :) If I am working in an enterprise scenario, I will not remember VLAN and IP addressing schemes ten years after installation. I really like the model that is presented here because it helps keep things in order. Just like building construction, the network or application must be thoroughly planned first. Everything should then be documented properly and installation or construction may begin. If the actual setup varies from the proposal, the document must remain a living changing being and evolve with the project. When everything is finished and operational, it must then be revised and checked and everyone involved needs to understand the key concepts at least. Very good article and I hope to see much more from you. Well done Mr. Malesevich. Thank you.
    860 pointsBadges:
  • Technochic
    I agree with the ideas for documentation presented. I have found documentation for some applications I have been asked to support to be sadly wanting. What I do NOT like is documentation written in the "code speak" of the system engineers. One document I tried to use wrote "install client for each scheduler" when in fact was not the CLIENT that needed to be installed but an additional SERVICE for the client that needed to be installed. Talk about confusing! I wound up calling support, getting the details and completely re-writing the documentation so my team members could understand and install this application when required without needing any assistance. Tech writers really need to read over their own documentation and then have someone who knows absolutely nothing about the app try following the instructions and make clear corrections as needed.
    57,010 pointsBadges:
  • SBelle1
    I agree that relevant documentation is necessary. In my experience, it should be prepared by those who have proven they are good at passing on information on other projects and applications. Whether they are recognized and certified as technical writers is irrelevant. If you ask around, you will find that everyone knows who the go to person(s) is for bring them up to speed on new and even old stuff. These people, also, provide great job aids and give tips on short cuts, etc. They prepare documentation that is a mixture of words, pictures, graphs, charts, diagrams, etc., so that however a person learns best, the information is provided in the form they can use. These people know the real world of IT and how people work. They know when to be specific, providing step by step instruction to get something done. They, also, know when to generalize to help anyone understand the overall concept. If they are not involved in the beginning, I can assure you that they will be rewriting the official documentation to improve it for use by those in the field. Thank you for discussing a much ignored requirement.
    20 pointsBadges:

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: