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.
Get in on the discussion in our Open IT Forum.
While documentation doesn’t necessarily make the world go ’round, it certainly keeps it spinning neatly on its axis when trouble arises. If you’re providing a product or service, you should be providing your customers with accurate information that allows them to effectively use and maintain that product, which translates into accurate and thorough documentation.
When an IT project begins, there is normally time allocated for documentation purposes, however, as development issues crop up, time is often siphoned out of the documentation components and allocated elsewhere.
Normally, documentation should be developed during the project, and reflects the changes that arise. At the project completion, it should be a simple process of assembling all the accumulated documentation, arranging it in a useful order and publishing it. This is the perfect world – but we don’t work in one. Too often, documentation is developed during the ‘last week’ of a project, and is handed to the person who has the least amount of work left, which is usually a junior team member.
Often, I find there is too much documentation. Some authors feel that the documentation should reflect the size of the project. Many times, the documentation is not well organized, it’s just slapped together with the hope that the client/user can figure out where the required information is buried. Without a well planned structure, there is a high incidence of overlap, duplication, and just excess information.
Some major problems with documentation are that it is a static, entirely manual process, and frequently there is no incentive to keep it current, or the time frame for updating the documentation properly is too short.
The only true documentation is the executed code and the corresponding source listings.
What characteristics should documentation have?
- It should be an integral part of any development effort.
- It should start at the beginning of the project and continue during the project lifespan.
- It should reflect the project elements, not a summary of the evolved project.
- It should be dynamic, changes should be easily incorporated.
- It should be structured and modular in composition, targeting specific audiences.
In my opinion, this can be achieved by organizing the documentation into 5 components:
5. Data Dictionary
Each component is targeted at a specific audience, with little overlap of information. Each component is self-contained, modular and can be used to reinforce another component. If a component is not required, then don’t create it.
The Overview component provides a high-level introduction of the product, and can be thought of as the marketing literature. It describes the functions and features as well as why the customer should buy your product. This component can be developed by an individual with marketing experience.
The Operation component contains the information needed by those individuals who are responsible for keeping the system functioning properly. This could be a formal operations staff, remote office workers, anyone who needs to look after the system. Some of this information would describe how to start/stop the application, availability, problem resolution processes, day to day processing, report distribution, verification of processing, backups, etc. This document should be created by the development and operations staff.
The Programmer component contains the source application code, compiled listings, logic flow processing, pseudo code, and other information needed to maintain and trouble-shoot the system. This document would be the responsibility of the development staff (programmers, analysts, etc.)
The Customer component has all the information needed to successfully use the application. It has procedures for inputting, extracting and modifying information. Problem resolution procedures are included and often developed as incidents occur. This should be the user’s bible and should be developed by the customer base, analysts, and development staff.
The key component is the Data Dictionary. It contains the information (meta-data – data about data) referenced by the other components. It contains data element definitions, file and record lay-outs, application logic definitions, report descriptions, process flow, sub-system relationships, etc. Theoretically, all the data elements would be created first in the data dictionary (data bases, files, data elements, data relationships, function definitions, reports, etc.), then propagated out to the various entities that need them (source code, security rules, etc.). Unfortunately, there are not many effective data dictionaries on the market and most of this is added to the programmer component documentation.
By separating the documentation, you are providing authors with specific places to deposit their information. Not everything will fall neatly into one of these components, you will need to convince yourself where the best fit is.
As an example, suppose you were trying to find the format of the birth-date element, you would look in the Data Dictionary or perhaps the source code. If you were entering this data element on a screen, you would look at the Customer documentation. In all cases the official definition would be in the data dictionary, and this would be propagated out to the required components. If a change to this data element was needed (expand birth-date year from 2 to 4 digits), it would start in the Data Dictionary and flow outward, thus making this change easier.
The next article will deal with each of these components in more detail.
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.