We are all aware of the situations where we couldn’t find appropriate documentation about specific IT artefacts that we needed. We spent hours, days, and weeks having various meetings, identifying relevant elements, their properties, and creating documentation by ourselves. Sometimes it led even to breaking the deadlines of the project. However, after a while, during some discussion one of our colleagues says that such documentation already exists, but in unexpected location. I know, your reaction was probably: What the ….! Mine as well.
Let consider the short example from below, and put it into context of IT Documentation.
“Huge amount of unrelated and unconnected maps will navigate you nowhere – especially if those maps have different scales and poorly described legends. No matter how much of them you have, it would be extremely difficult, if not impossible to organize the trip.”
The very same rule applies to the IT Documentation. No matter how much and how detailed documents you create, there are not useful for others if they cannot locate and understand them. Creating unconnected, unorganized and isolated IT Documentation that doesn’t apply company standards is non-productive and has no vale for the business. Not only it will not be used by others, but it will take your time to produce it as well. If you create huge amount of such documentation for yourself, you’ll also lose control and overview over the time.
Please note that this text does not discuss the value or the need of the IT documentation itself, but rather the way it should be applied if identified as needed and valuable for respective enterprise.
There are several standard-based questions you need to keep in mind when documenting IT artefacts, which descriptions should or is planned to be used by others:
- Is the structure of the Documentation of the IT artefact you’re trying to describe already defined in your enterprise? Meaning, what properties or metadata should you document, how, and to what level. This actually can be considered as “common language” used to describe IT Documentation and should be understandable by all relevant stakeholders. If structure is defined, first fill those information required by the standard and then extend with the information you additionally find valuable or useful. If not, speak with your colleagues to find most appropriate solution. Do not define anything only by yourself. Speak with your colleagues. Always.
- Did you already considered the existing organization of the IT Documentation in your enterprise? Meaning, did you find appropriate hierarchical place for Documentation of the IT artefact you’re trying to describe. If you document something and put it on the wrong place, there is a small chance to be found and used when needed. For example, you should never put documentation about application object in the category where you document technology or data objects. Also, a category aimed to store metadata about “data fields” should never hold information about “table properties”. Business definitions should be saved in folders with business context – technical in folders having technical context, etc. You get the picture. The biggest problem is however documenting something that might be useful at enterprise level only in the personal, or in the folder known only to you. Don’t forget, your colleagues are not seers to know that there is something in some folder that probably might help or use them.
- Did you considered the possible tool your enterprise uses to document IT artefacts? Meaning, do you have sufficient information about the possible software that is used in your enterprise to store information such as metadata, enterprise architecture, solution designs, etc.? This is really important aspects. If you use wrong tool, your documentation will be probably never used. At least not functionally and not in the expected context.
- Did you already spoke with relevant people from your or other teams? Meaning, did you ask relevant people from your or other teams if same or similar documentation already exists. There is a slight possibility that similar or same documentation regarding existing IT artefact already exist, thus, it is recommended to always discuss with others to avoid duplication of the content or unnecessary work.
If you considered all four questions from above, your IT Documentation will be valuable, useful, and helpful to others for sure. If you miss any of those, there is a huge chance you’ll end with huge amount of non-useful documentation that costed you and your company pretty much time.