By Rich Hunsicker, Senior Consultant
It is a love/hate relationship: we hate to do it but love having it. From a development perspective, we typically have the specifications and a design document (in some form) from which we build the application and its surrounding processes. We may even have some data schema and overall process/logic flows. Between the delivery of these requirements and high level documentation and the implementation of the process and application is where the details become scarce.
We all know that documentation is required in some form if we are going to transition an application to another person or organization, or it may be a part of the overall project deliverable. We are often against tight deadlines, and documenting the process and procedures becomes secondary; even putting the comments in the code which will help us figure out the “whats” and the “whys” we created this logic. Documentation is on the back burner until we rush to gather the information at the end, and wonder what does this code do or do we really need all of these dimensions and variables and why do we have these processes that seem to do nothing.
We have all had the situation where a modification is required; case in point, modify processing to be driven by a fiscal calendar rather than by calendar date. In this modification, it was determined that changes had to be made to the scripts to incorporate the fiscal day which was not provided in the source data. Knowing what data was available and what needed to be included, either calculated or extracted from other sources, often expedites the completion of the modification. Knowledge of all data sources, input and derived, including the variables created in the scripts and through dynamic definition, is invaluable in correctly modifying the user interface and ultimately reducing data bloat by eliminating fields once required and now no longer needed.
Just do it. Document as you go. Most development tools provide some method of capturing and exporting schema and other details, field usage, variables, etc. Review the different forums for tools created by other developers that will retrieve information from your application and processes. Detailed below is a list of items that we have found useful in our documentation. In the end, the time you save may be your own!!
- Initialization and set up processing and procedures. Provide a step-by-step task list for establishing directory structures, libraries, references, etc. Included in this information are environment and other reference data and files.
- Security and user access tasks and procedures.
- File transfer protocols and back-up procedures for data and applications.
- Process flows with inputs and outputs. Incorporate the processing explanations as well as exception handling (and not just call support). Data from external systems should have contact information of the direct and supervisory personnel. Developer and analyst contacts for the external data are as essential as the support contacts. Assure that your organization receives change notifications from upstream systems and provides the same for downstream.
- Create code and process comments in the respective applications and procedures, and then use this information, noting the source, load script, process flow, etc., as the basis for the documentation. Expand and explain these short descriptions.
- Complex formulas and expressions should find a home in the documentation. Not only do these entries serve as examples, but will assist those that have to modify such entries (which always happen) by explaining the logic and processing behind these technical solutions.
- Detail standards utilized in User Interface, which will form the basis for the UI mechanics and “help” documents. Document derived values and variables used in selection mechanisms, such as list boxes, buttons, etc.
About the Author
Rich is a Senior Consultant with over 30 years experience in IT, working with both large and small businesses. More than ever, Business Intelligence is a critical component that allows companies of any size to understand their underlying data and direct their business plans and projects. Often these perspectives lead to finding over expenditures, under utilization, duplication, etc., which impacts a company’s bottom line. Working with our clients to find these “gems” is part of our focus.
