WHEN I FIRST STARTED this article months ago, I was quite sure I had Net Science’s documentation nailed. Then things got busy. Three months later, I have experienced an employee onboarding and offboarding and a client onboarding and offboarding. We have also changed password management tools and our user training offering. So no, I did not have it nailed.
Most of us know that documentation is never finished. Even if we believe we have it covered, something will happen to make us realize we are wrong. Sometimes, it is one of the above situations. Other times, it is much bigger, such as outsourcing your help desk or a pending merger or acquisition. IT documentation is a river that never stops flowing.
Here are some policy issues and parameters you need to build a great documentation framework.
The Easy Stuff (Newtonian Mechanics)
What is the simplest information you track in your business? How about your clients’ hours of operation and contact person(s)? Easy? But these hours may vary by season, or there may be operations in multiple time zones. Contacts can change, go on vacation, etc. With remote work, these issues are ever more challenging.
Now what about holidays (for your business and each of your clients)? For those of us who do not offer true 24/7 support, what about clients that require out-of-hours support? Don’t forget to consider who can open support tickets at each site and when (especially if this is billable time). Speaking of designated site contacts, what if they are unreachable in an emergency?
Along those lines, how do you verify the identity of those calling in or opening tickets for support? And how do you verify that you are sharing confidential information with only those you should?
The next thing to consider is supported devices and operations. For example, do you support issues on a home user’s network (think of Wi-Fi on 802.11b routers)?
What about users on travel? Do you support only company-owned and managed devices, or personal PCs, Macs, tablets, and phones? What about borrowed equipment? If you have a site in Azure, how is that “mapped out” and documented? And for those sites with virtualized desktops (Azure Virtual Desktop or others), how are they managed, secured, and documented?
What if the client’s standard is AVD machines, but the users requested the use of a different solution? And if you are still old-school and most remote work is by means of SSL VPN client connectivity over RDS to a desktop in the office, what if they want to use a web-proxied solution? Even the easy stuff can be hard.
The Harder Stuff (Quantum Mechanics)
Now we get to the more complicated stuff. How about documenting the site itself— hardware, software (on-premise and in the cloud), the location of data (again, on-premise and in the cloud)? And let’s not forget security protocols, including identity management and permissions, and perimeter and endpoint protections, and any zero trust and/ or secure endpoint secure access (SASE) that might be at play. What about Wi-Fi, possible site-to-site radio or laser links, or even 4G/5G connectivity or fallback?
We try to build a flexible but consistent methodology for the creation of all our documentation, to make sure that we can always find what we need (and expand upon it) as efficiently as possible. That does mean that we often end up with some “null space” at some sites that while not required there, is necessary to make the overall structure “cohere” better. This also allows us to make sure we do not miss things, as having a consistent structure for documentation makes it much easier to find the holes in our processes and discover what we’ve missed.
The Metaphysics
Now we move to the “between the lines” stuff, documentation not of things, people, or policies, but of the “reality on the ground.” This covers a broad range of issues, from the truly technical (permissions structures and who is empowered to change them) to areas more akin to HR than IT (an entirely different kind of “permissions”).
This seems like the time to broach the subject of your “permissions” as an IT partner. For example, are you allowed to call contacts on their cell phones, and under what circumstances? What about physical access to their site? Do you have keys, fobs, access codes, or other means of privileged access, and if so, in what manner is your access constrained?
Now let’s move back into the technical realm. Do you have a truly comprehensive listing of where all your clients’ data resides, who has access to it, and from where? What about how it is protected and backed up? And who has access to the management of that, besides your firm? What about remote access methods; are they all managed by you? Are you sure?
Before we move on, we should touch on the most sensitive of issues: relationships. We all have some “client relationship challenges.” Some of our sites have staff that interact with all of us, others that will only work with just some of us. Others have certain staff members who can only be handled by one of us. And some folks just never respond. How do we document that?
Tools are important, and some documentation tools are far more flexible than others, especially when it comes to this sort of unstructured data. But no matter how great the tool, first you must have a nice, extensible architecture underlying it. You may have noticed there are not specific tools called out here, largely because there are so few “right” answers. The best answer is to build your framework the way you want it, and then find the tools that will support that. Do not let the “tail” of the tool “wag” the dog of the process.
In the Final Analysis
IT documentation has more than a touch of alchemy to it. Some things are cut and dried and very straightforward to track. A large part of the challenge of doing this well is figuring out what we do not know. And then, once you really do have a handle on it, you must determine how to manage and structure all that data.
To return to our original premise, you never really know how good your documentation is until you start changing things, hiring and firing, onboarding and offboarding clients, and changing vendors, tools, and processes. And don’t forget the river flows, and everything changes. As challenging as getting documentation right is, you must not forget that it constantly changes.
Think you’re ready to try for that Black Belt in documentation? Consider what it would take to outsource your help desk or NOC. Ask yourself, what if we never did another L1 or L2 ticket ourselves? What don’t we have properly documented? What changes have we missed? How do we properly transfer that knowledge and keep it current? The river never stops flowing.
JOSHUA LIBERMAN is president of Net Sciences, MSP 501 member, and the best little MSP in New Mexico. A former mountaineer, martial artist, and lifelong photographer, Liberman is widely traveled and speaks several languages. He is an ASCII Group board member, writes and speaks publicly, and raises Siberian Huskies. His wife, Heidi, calls him the Most Interesting Geek in the World.
Image: Adobe Firefly
