The most neglected aspect of any IT shop is documentation.
Think about it? If a new person comes on board in your IT department, how long does it take for that person to get up to speed before they can be assigned their first task? I am not just talking about programming and coding, but any aspect?
Walking into a new work environment is daunting to the best IT professional. Most often the learning curve is huge as the newbie tries to digest the various business rules, principles, best practices, and data structures of your systems.
Usually the newbie finds they are sitting at a desk, often without a computer in those first days, and reading binders of photocopied user manuals – screenshots with minimal text written by co-workers. After that they are most likely given stacks of source code to look at with little or no context as to how things are put together.
Even worse is the existing co-worker, who knows System A like the back of their hand, but now has been asked to do some work on System B.
Face it, most IT environments are lax when it comes to documentation. It's an afterthought. Or the documentation has become obsolete as the system evolves and changes to never-ending requests from the users.
Good documentation practices are the key to knowledge transfer. Getting newcomers up-to-speed quickly so they can be as productive as you need them to be. Your department did not go out and hire that new analyst or architect because you knew six months from now they might come in handy? Most likely you need that person now, and you finally received approval for the new hire, or the transfer from a different area.
Good Documentation is the key to a successful transition.
This means that documentation practices must be put into place so that new hires can be productive as quickly as possible. And what IT manager wouldn't like to show their superiors how quickly they can get their staff at full productivity?
In my experience, I have found the following levels of documentation to be the most effective. But I do admit, this is my own preference, and the luxury of such detail may not be affordable to every environment. But I do believe that more is better, and accuracy is the key to success. Here are my top preferences – using the names that I know these documentation structures by, their purposes, and their target audiences both before and after a project is completed:
The Vision Document – Also known as a high level design
This document most often is originally targeted at high level management. The language is non-technical and describes the intention of the newly planned set of components. This document contains the following pieces of information:
Overview – a set of paragraphs that describe the overall purpose of the system.
List of components - a high level statement of each component describing what each component is for , what data is captured, who uses the component and why, and how it interacts with other new or existing components. Simple UML object diagrams are very helpful to the reader as a well drawn yet simple illustration can quickly bring establish the components purpose quickly, with text to describe the picture and add those subtle nuances that a simple picture cannot detail.
Mock ups of the user interface to show the flow of high level events is a great additional feature.
A Realization Document
The Realization document is simply the finished version of the Vision Document after the project has been completed and implemented. Hence forth, as future revisions are made to the components of this system or project, it is the Realization Document that is updated to reflect those changes.
The language should remain at a non-technical level – but now that all the unknowns have been answered, the level of detail can be slightly greater to answer the readers questions before they are asked.
There is one additional piece of information needed in the Realization document:
List of changes – a short list of each change to the system since the vision document with a description of how it changed the component, why the change was necessary, and the benefits the change brought to the overall system.
Mock up pictures of the user interface should always be replaced by actual screen shots of how the user interface really does look now.
The Detailed Design
I like to think of the detailed design as the workbook that the entire team will use as the various components of the system are flushed out and documented. A well structured detailed design document will allow multiple team members to update their specific sections of the document simultaneously, each building off the depth of the other team member.
This document has several audiences:
Managers will use this document to determine the progress being made during the development cycle, or after its completion as a reference to see what components were built in which ways.
Technical Architects will describe the physical components such as network servers, communication aspects, security aspects, and hardware requirements.
System Engineers will describe the various components of a system, subsystem, or subset or groupling of components. They will use this document to describe the break down of the components to the object the level, and the relationship of the objects to each other and how they interface with each other. The business rules to be addressed by the system are detailed and assigned to each object and their role in enforcing each rule. These rules are the direct map back to the system requirements either gathered by or given to the engineer by a business analyst. As well, this document should contain a high level view of the items to be included in test cases – for both system and end user testing.
Software Designers will use this document to break the described objects down into classes, and to translate the fulfillment of those rules into logical algorithms – most often using pseudo code or examples of existing logic. The software designer will also pinpoint where common or reusable pieces of logic should be either created or employed from existing packages.
Database Analysts (DBAs) will use this document to assist both the Software Designer and the Software Developer in optimizing the structures of tables, focusing on primary key, data integrity, referential integrity, naming convention and normalization or de-normalization strategies.
The software developers will use this document to extend the software design into actual source code, documenting which source code pieces are used to fulfill the design, maping the memory objects to the database table columns, working out stretegies to achieve complicated objectives, such as node to node timeout mechanisms, edit check validations, and even image resources used to decorate the interface.
At the same time, all the above persons will maintain a section at the back of the document to track known issues, resolutions to issues, and general notes of things to look out for – such as features of third party components like ODBC or JDBC drivers , COM, CORBA, or included package items.
Each author of this document should use diagrams and models to help the other members better understand the nature of relationships and attributes of the various aspects they are describing.
My preference has for the last several years been UML (Unified Modeling Language) 2.0. My reason being that in my own experience, the sets of diagrams – from use case diagrams to assist in requirement gathering exercises to physical, and logical views allow team members to create a 360 degree model of the solution.
The benefit of such a document written in this manner is that it keeps everyone in the loop as to all aspects of the project – that component of the project of which they are mutually responsible. There have been many examples in my own experience where this technique combined with comprehensive UML modeling has caught development issues very early to be dealt with before they become oversights- costly oversights that might spell the failure of the total project.
After the initial document has been completed, just prior to the implementation of the new system, subsystem, or components / modules of the system, these document should be signed off by all stakeholders. In truth there are several sign off points – when reviewing at various stages to provide status to all parties concerned.
As with the Vision document, this document will be your source of information for future maintenance or enhancements to these components. And those changes must be tracked in this document, or else the document quickly becomes obsolete.
The end result
The result of this documentation is a comprehensive set of reference that should be easily understood at various levels of the development team, management team, departmental executives, and executive.
These documents should be stored electronically in a central repository – easily accessible to all concerned parties. More elaborate libraries – such as SharePoint Repositories, Lotus Notes Document Databases, or even version control tools like CVS should maintain version integrity of the documents and be easily searched for by any one looking for them by simple key word searches. To simply shove these documents into a shared network drive organized loosely by folders will greatly diminish the impact these documents will have on knowledge transfer and managements desire to even attaempt to look for the information will be eroded to the point of non-existance.
The Big But …
"That all sounds wonderful, Fred – but our system is a decade old now? Should we document what we already have?"
All departments no matter how busy do have points of time where team resources are idle. Assigning existing components to be documented during such downtime – by the subject matter experts – is not a wasted effort. Every system has a life cycle. At some point that system will come up for maintenance work or be replaced by a new system. At some point there will come a time in the future where such doicumentation will be seen as invaluable, and the genius who showed the foresight to action this task will be seen as a strategic leader with pro-active vision.
And who doesn't want to be seen in such light by those who decide your future.
