Skip to content

EricN Publications

Publications by Eric Niewoehner

Menu
  • Non-Fiction
    • A God Thing
      • Rachel’s Prairie
      • Adolescent Meditations
    • Oakland
      • Old Buildings Can be Creepy
      • Food for Thought
      • Dust in the Wind
      • The Arc of Travel
    • Iconium
    • Thinking Out Loud
      • Stranger than Fiction — The Case of Mary Fulp
      • Social Security – When Will America Face Reality?
      • Is Juneau Running Out of Diesel?
      • The Volkmer Effect on Alaska’s Congressional Representation
      • The Tragedy of Russia
      • Are We In A Recession?
      • Where Does Inflation Come From?
      • The Mail-In Ballot Experience
      • The Debt We Owe
      • The Solution to Paying Off Student Debt
      • Student Debt: Are Colleges to Blame?
      • The Problem of Student Debt
      • Fighting Inflation – A Trip to the Grocery Store
      • Ukraine – Poland 1939 All Over Again
      • Broken: Is Public Education Beyond Repair?
      • Transparency and Critical Race Theory
      • The New Wave
      • The Pro Act and YouTube
      • Almond Abstract and the Pursuit of Happiness
      • Open Letter to Major League Baseball
      • Tribute to Rush Limbaugh
      • Why Parler?
      • Adults in the Room
      • The Invisible Hand
      • Transparency
      • Fake News Update
      • Solution to Fake News
    • Old Friends
      • The Ideological Origins of the American Revolution
        • Sources and Traditions
        • Power and Liberty
        • The Logic of Rebellion
        • A Note On Conspiracy
        • Transformation — From Reaction to Revolution
        • The Contagion of Liberty
      • The Road to Serfdom
        • Introductions — Or Before You Begin
        • The Road Once Traveled
        • Are You A Nazi?
        • Are You A Socialist?
        • Individualism
    • Lessons Learned
      • Change Management
      • Documentation — The Key to Continuity
      • A Lesson in Time Management: The “90% Rule”
    • The Pandemic Journal
      • When Does Ten Percent Matter?
      • Federalism — Or Intentional Chaos
      • Faith (Part II)
      • Faith
      • The Big Surprise
      • Teleworking
      • The Invisible Hand
      • Unbelievable
      • Rethinking Education
      • Perception
      • Selfie and the Mask
      • China
      • Strategic Globalism
      • Risk
      • Media
      • Unknowable
      • Home Schooling
      • Grocery Chronicles
    • When Few Were Watching
    • The Advent Conspiracy
      • What’s Missing
      • Cash Only Please
      • Worship Fully
      • Give More
      • Christmas — It’s a Tide, not a Day
  • Fiction by Eric Niewoehner
  • Technology Publications
    • Technology Blogs
      • A Play on Words
      • Spam Update — How to Avoid Spam
      • Facebook — A Sickening Feeling
      • Can PayPal Be Trusted?
      • Are You Ready to Rumble?
      • The Alaskan Congressional Rodeo
      • The Gift of Gab
      • Facebook – What Say You?
      • What’s Up with Parler
      • Out of Control? – Security Vulnerabilities in Control Systems
      • The Case of Lorie Smith
      • Facebook — Impersonated Accounts
      • The Case of Josh Renaud
      • SHAKEN, But Not STIRred
      • Can GoDaddy Be Trusted?
      • Ransomware and the Mechanical Pencil
      • Tracking Scams in Phone Messages
      • Disaster Recovery — The Case of Parler
      • Computer Vision Syndrome: CVS Update
      • Why Parler?
      • Computer Vision Syndrome
      • Passwords – the Gremlins of Cyberspace
      • Spam Filtering: Mastering Your E-mail
    • The Facebook Safe Space
    • Technical Documentation
      • Welcome to DOGland
      • Windows 10 and Computer Vision Syndrome
      • Sustainable Printing
    • The Tech Community
    • Introducing Substack and Locals.Com
  • Contact
  • About
Menu
Documentation

Documentation — The Key to Continuity

Posted on February 21, 2023February 25, 2023 by Eric Niewoehner

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.

Sample of a Windows 3.1 Desktop
Sample of a Windows 3.1 Desktop

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.

My Office at the USFS.
What would happen to your organization if your IT specialist suddenly vanished?

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

Read More of Lessons Learned
Share on Social Media
twitter facebook linkedin emailtelegram

Related

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

EricN Publication Logo
  • Facebook page for EricN Publications
  • LinkedIn page for EricN Publications
  • Twitter page for EricN Publications

Recent Posts

  • A Lesson in Time Management: The “90% Rule”
  • Documentation — The Key to Continuity
  • Stranger than Fiction — The Case of Mary Fulp
  • Change Management
  • Social Security – When Will America Face Reality?

Popular Posts

Categories

  • A God Thing
  • Advent Conspiracy
  • Alaska
  • Bernard Bailyn
  • Documentation
  • Economics
  • Education
  • FA Hayek
  • Facebook
  • Faith
  • History
  • Lessons Learned
  • Life
  • Missouri
  • Non-Fiction
  • Oakland
  • Old Friends
  • Pandemic Journal
  • Politics
  • Security
  • Social Media
  • Tech Blogs
  • Technology
  • Thinking Out Loud

Archives

  • March 2023
  • February 2023
  • January 2023
  • December 2022
  • November 2022
  • October 2022
  • September 2022
  • August 2022
  • July 2022
  • June 2022
  • May 2022
  • April 2022
  • March 2022
  • February 2022
  • January 2022
  • December 2021
  • September 2021
  • August 2021
  • July 2021
  • April 2021
  • February 2021
  • January 2021
  • August 2020
  • July 2020
  • June 2020
  • May 2020
  • April 2020
  • November 2018
  • August 2018
  • April 2018
  • February 2017
  • November 2016
  • October 2016
  • July 2016
Copyright Notice

All articles are copyrighted material from Eric Niewoehner.

  • Facebook
  • LinkedIn
  • Twitter
© 2023 EricN Publications | Powered by Minimalist Blog WordPress Theme