The aim of this article is to attempt to explain why in-house documentation is important for IT departments and what can be done if there is no adequate system in place to fulfill the requirement.
The information here is directed towards people working in technical roles within a company, such as systems administrators, software designers and testers, technical managers and supervisors, and anyone who feels that their departmental documentation may be somewhat lacking or even non-existent.
I myself am a great proponent of encouraging the creation of useful documentation and have created quite a lot in my years of working with computer systems and in other technical work, where it has always proven to be very useful, not only for myself but for others too.
The advantages of making good documentation
When you have a well-organized technical department with the right staff and each person knows their responsibilities and can perform them well, everything runs like clockwork – until something goes wrong! A person leaves the company (perhaps suddenly, for one reason or another); someone has to go on extended sick leave with little notice; an employee goes on vacation or even has to take a day off, and this means that other staff need to take over the duties and roles of that missing employee. What if two, three, or more employees were off work, say due to an outbreak of illness, or an important training course? Can the department still function? They may have no choice but to battle through as best they can manage. But why make it harder work than it needs to be?
I have seen it myself several times working in IT and also been on the receiving end of having to take over a role because someone else was temporarily absent or had left the company at short notice and the handover period was far too brief to be able to acquire enough information to take over the required duties of the missing person. You may know the concepts and general workings of the tasks and projects in question, but you still need to know all of the ins and outs of how those things are performed locally, day-to-day in the environment that you are working within.
As is often the case, the role has to be learned, at least for how it all works within the company, but often it needs to be learned from scratch because nobody else has the expertise in the task as they are only experts in their own roles. This now wastes a lot of time with retraining and certain tasks may need to be put on hold while the training is being completed. The answer of course is being prepared through cross-training, and good documentation is the cornerstone of that. It provides a solid reference point that can be used as a prelude to training, as well as something to refer to afterwards, especially if there was not enough time to train somebody properly prior to a key person being absent.
The documentation not only provides the information needed to perform a task for yourself or others currently working in the department, but will also serve as either a reference for later employees or at least as a template or guideline as to how similar documentation should be done in the future. It also provides managers not directly involved with the daily tasks to be able to look at the documentation and see how the role is performed and may be useful for future planning.
So why is documentation not done?
There are several reasons why a department may not be able to produce documentation, but where such documentation is required yet not produced means there could be a less than rigid system of control within that department.
It may be that creating documents is an overwhelming task – perhaps there is so much physical paperwork that needs converting to electronic versions; the people who should be creating the documents just don’t know where to start or how to organize it; there is not enough manpower available or a lack of time; a system exists but it has become too complex to use. These are problems that should be overcome if trying to run an efficient department.
One very common issue, especially in IT departments, is that administrators don’t want to share the information that they have. They may think that once other colleagues know how to do their tasks then their particular expertize becomes less ‘unique’ and therefore their job is less protected. This is false thinking and the person should look at it from another angle – that others are also sharing their information and that each person can learn other skills and increase their level of knowledge. Creating documentation for your role also shows higher management that the person can do their task and understands it well and demonstrates the workings of the job. It also gives their peers confidence in their work and vice versa.
Admins and technicians may feel that they are not very skilled in producing good documentation, either because of poor grammar and spelling skills or perhaps the language it needs to be written in is not their first language and they worry about getting it wrong or being ridiculed for their shortcomings. I think it is generally accepted though, that technical people whose primary job is a hands-on role are often less strong in areas of documentation. I would say that imperfect documentation is better than nothing at all. A document that gives some indication of the work involved and shows who the author of that work is means that there is at least contact information where someone else knows who they can talk to about the subjects in hand.
In-house documentation does not need to be grammatically perfect, but it should be as readable as possible and make sense to others. At least run it through a spelling checker before publishing or distributing it. A document full of easily fixable errors shows a lack of attention to detail and may lessen the confidence the reader has in the content of the document and the author who has produced it.
How to create a structure for documenting
The first thing you need to do is to decide how documentation is going to be done within your organization. You could invest in some fancy DMS (Document Management System) but that might not necessarily be a good first step. It might be expensive to buy, set up, and train people to use and once your time and effort is so much integrated into the system it might be difficult to back out if you later find it is not the ideal system for you. Perhaps a large department with an urgent demand for masses of documentation to be produced and managed, and especially if securing documentation is important, might consider talking with the software manufacturers who produce DMS software to see what options exist, but you need to consider carefully what you really need.
Often a much simpler method can be employed and still be very effective. Even storing documents in folders on a networked share can work for less demanding organizations. Folders containing documents can have basic security applied to them so that only certain people or user groups can access the content. This also has the advantage that must always be considered – it must be easy for users to store and to retrieve documentation. I have seen methods applied where the structure has just been added to without too much consideration of where things are located and it then becomes quite difficult to find anything.
Microsoft Sharepoint and web pages are becoming more popular for the management of documents and some data as well. For this to succeed, users need to understand how it works, as sometimes the interfaces and workings can seem confusing and if people cannot find where their documents are supposed to be stored, or they cannot easily find out how to retrieve a document, then they may just end up storing data on their local disk out of frustration. I have seen it more than once where the management of documentation has gotten disorganized and it ends up worse than having no system at all. Data that is not immediately accessible on demand is part of a faulty system.
The things to consider when planning a documentation system are:
• Users must be able to store and retrieve documentation with minimum effort and frustration.
• If a system has any complexity, then you must train users how to use it for it to be effective.
• If security of documentation is an issue then make sure you adopt a system that can cater to those needs fully. This not only deals with doing virus and malware checks, but also preventing hacking or other unauthorized access.
Andrew Petrovic