I have observed two kinds of IT personnel – those who never write anything down and those who do.
Documentation is part of the Lessons Learned series.
When teaching Information Management I generally had as students people who were not IT specialists. They were managers, business owners and military officers. In essence, they had to trust their IT specialists. So I asked them, “Would you trust anyone who carried all the information about your IT systems in the gray matter between their ears?”
If anything punctuates my career, it is documentation. We divide our pages into paragraphs. And our sentences are paced through the use of commas, semi-colons, colons and exclamation marks. We could only hope that each sentence, representing events in our lives, are terminated with the simple period. That wasn’t my career. Let’s just say there were a lot of “rough drafts.”
Documentation doesn’t come easy. I was a very creative individual. I would get up in the middle of the night just to try a new idea I had dreamed up. Software programming was a lot of fun. But no matter how hard I tried, it was apparent that the end-user would need some help. I had to design a turn-key product, something that anyone could install and update on their own. I had to reduce complex operations to simple menu-selected items. Occasionally I had to hire programmers and network administrators and I needed to have clear information from them. Documentation was one of those boring things of critical importance.
When Windows came along I found the perfect solution to the documentation problem. I was a network manager at that time. For each new feature I added to the user’s Desktop I included links to help documents. Users became less dependent on me. User experiences became the basis of changes to the documentation. The results were better informed users, faster resolution of problems and less time in end-user support.
Yet nowhere was documentation employed with more seriousness than with IBM. I began to work with IBM when I was hired by the US Forest Service (USFS). The USFS utilized IBM AIX servers and I had to work with IBM consultants on a regular basis. And they went by the book! Literally. I grew to greatly admire the thoroughness of their documentation. With their help I was able to better understand the AIX operating system and how it integrated with the IBM firmware on the servers, storage arrays and tape libraries.
The USFS would eventually move away from IBM systems toward a cloud solution. But I simply continued with the IBM model. A visit to my website will list numerous “DOGs” that I assembled over the years. These Daily Operation Guides were vital for documenting the tasks that we were likely to encounter. My problem was rather practical – I was getting older. I no longer could retain knowledge on tasks rarely done, especially when I was bouncing between Linux and Windows. So I began to write it down. When a problem re-emerged six months later, I simply looked it up in one of the DOGs.
So it is certain truths emerged about the transference of knowledge.
IT organizations should have documentation standards. I have noticed that code writers will often have strict standards, especially in the open source arena. Most of what they are thinking is included in the code itself as “comments.” But regarding problem resolutions, writing out the solutions is imperative. It must be done in a systematic manner with someone in charge of the material. I have known folks to say, “Why don’t we just document this in a Wiki?” Hmm. Anyone who has tried to post something to Wikipedia will soon learn that they keep to rather strict standards. You can’t just write anything. Most subjects have a managing editor or team. Wikipedia has their own roving editorial specialists who will check grammar, document structure, and references. Open source programs, like LibreOffice, have development “communities.” A casual review of their code standards makes it quite clear that you will first need to understand how code is developed, documented and tested.
Documentation is what you ask for – don’t expect people to just do it. As a business owner or manager, it is your job to insist on it. Yet I have seen time and time again how organizations document nothing. Personnel leave with the passwords. I have even seen laptops disappear. One customer had lost access to their entire Active Directory domain because the consultant they hired did not document anything.
Documentation should be an integral part of an IT professional’s job performance review. I find it remarkable that in most fields with a post-graduate degree, the ability to write is tantamount. Yet I have seen over and over again very bright people who love their work simply fail to write anything down. Yet if they have an MS or PhD after their name, I would expect they are fully capable of writing things down. They fail to do so because there are no consequences. Managers should know what their employees are doing in the IT arena. And they should be able to find the documentation and read it.
Contributors should be acknowledged. If documentation is part of a performance review for an IT specialist, it should be reasonable to acknowledge, if not reward, IT professionals who articulate their work so others benefit. In the academic world, bibliographies and footnotes, prefaces, forwards and afterwards are all used to give credit to sources of knowledge. Technical documentation should be no different. If you look over my documentation section you will notice that I take credit for anything I write down. It is in my resume. My manager may not care, but I can tell from the traffic on my LinkedIn site that others notice.
Documentation is critical to the long-term mission of the organization. It is remarkable how disruptive a lack of documentation can become. How many times have utility lines been severed because their location is either not documented or the excavator simply did not bother to check? As noted above, an organization lost access to its entire Active Directory tree because knowledge was not passed from a contractor to the manager. How often have critical applications that have been used for years are suddenly failing because the programmers have long since gone and no one knows how the program works? Documentation should be part of the review process whenever an IT incident occurs.
Alas, documentation is what defines civilization. One of the key elements that distinguishes a “civilization” is the transference of knowledge through writing. It is ironic to see organizations risk their future success because they fail to transfer knowledge.
As noted above, documentation is not something that just happens. You learn to do it. It is not always exciting work, but it is quite gratifying when you have to return to a complex problem months later and see what you experienced clearly written on a page. Your colleagues also will appreciate the information because your experience is transferable. Managers will need to help IT specialists develop documentation skills. Writing is easy for some, more difficult for others. But it is totally inexcusable for highly complex information to simply exit a company. Don’t blame the IT specialist. That is 100% management.
If you are interested in learning more about how a technical document is constructed, check out “Welcome to DOGland”.
© Copyright 2023 to Eric Niewoehner