Wednesday, January 18, 2012
Essential Documentation for System Operation and Maintenance
Have you ever purchased a new car and attempted to open the hood but could not figure out how the latch works or where to find it? How about the release button for the trunk or fuel inlet? Same problem? Chances are the first thing you reached for was the Owner’s Manual. Put another way, it is nothing more than the system documentation for your car or truck.
You surely would not want a mechanic to randomly replace parts on your car or truck until the right one was found to fix an existing problem. I am quite sure the same holds true of your EDI system. You would definitely not allow someone to make changes to Trading Partner setups, maps, file paths, etc. without completely understanding not only why a change is necessary but also the impact and results of the change that is instituted. This is where the importance of system documentation comes into play.
If your system is updated, your system documentation should be updated. If your system remains static, then your documentation should also. Maintaining the documentation in an easily accessible location promotes best practices and is essential when trouble shooting a system, especially a system with which you may not be entirely familiar. Anyone that may be required to use a system should also have access to the documentation on how to use a system. Keep in mind that it may be wise to store a backup copy of your system documentation on a drive other than where your EDI system resides for disaster recovery in the instance of system machine failure.
What to Document
A good approach is to develop your documentation that is in direct correlation with how your EDI system is setup and used. A good start would be to list all Trading Partners at the forefront to give you a base on which to build your individual mapping, flow chart and process components upon. These should include listings of interchange sender and receiver id’s, file formats, communication protocols including FTP or URL credentials (do not forget the user id’s and passwords) which inevitably get squirreled away to some folder once they are setup and deployed, no one can seem to ever locate them again. An overview or listing of relevant transactions being processed is also a good idea to include since when a segment needs to be added to a specific transaction set, you can determine relatively quickly the scope of the required update.
Next should include a listing of all processes executing actively on the system including a brief explanation of processes that may be invoked from outside of your EDI system. These could be processes that would archive files or create carbon copies to name a few. This section could also include scheduled tasks or triggers including timing and duration and what they are used for, database tables used for storing or retrieving data including ODBC or data connection strings with credentials, reports generated and how they are distributed including individual email addresses or distribution lists in use.
Next in your system documentation, list your system standards that should be followed when adding a process, directory, trading partner, maps, etc. to keep your system standardized and concise. There is nothing more frustrating when attempting to debug an issue and you discover four different methods named four different ways stored in four different folders which essentially are used to accomplish the same task.
Finally a detailed section on each trading partner setup should be included where all unique information such as maps, file specs, data formats, file definitions, jobs and processes and any special processing, reporting or notification should be documented to not only allow you to rebuild a system if required, but are invaluable when trouble shooting day to day issues that can and will arise.
Last but not least, do not forget to create and include a contact list which contains not only names and email addresses, but also lists best times to call plus a secondary or tertiary contact in case the main contact happens to be on vacation or simply out of the office when they are needed the most.
Creating and maintaining system documentation is the ultimate reward for having spent countless hours on developing, testing and deploying a new system dedicated to long term service and will provide comfort in allowing unfamiliar or first time users access to your system with the full knowledge that if a questions comes up on how to open the hood, more than likely it will be found in your system user manual.