How Do You Document Technical Procedures?

ChadDa3mon writes "I work for a large MSSP type operation and we deal with a plethora of vendors, versions, and .... skill sets. We're facing a critical problem as we grow when trying to deal with these varying degrees of technical competency. The end result is we're getting to the point where we have to document every procedure and process, no matter how mundane or 'common sense' it may seem." How, ChadDa3mon wants to know, can complex skills be documented to account for various users? Read on for more details of what he's seeking. "I've got a picture of how I'd like this to work in my head, but I can't find any software out there that seems to go along with it. I'm a big fan of keeping things simple, so I'd like to start with high level overviews. Each step in the process would be a general statement like 'Look for valid traffic on the monitoring interface'. For those who already know what 'valid traffic' means, it's easy to follow. However, if there was someone who was unsure what it meant, there would be a link they could click on that would pop open a new window (or something similar) explaining in detail what we're looking for and how to find it. It's my hope that using this process, people aren't just blindly running commands, but gaining an understanding into what that command is, and why we use it, what to be aware of, etc.

This seems like a job for a flow chart, but I don't like the setup of any of the ones I've used, such as Visio. It could also maybe fulfilled by a wiki, but there's so many out there I don't know where to start. I have to assume I'm not the only person who's facing a problem like this, so I'm hoping someone else out there can make some recommendations."

Comments

Re:bad

[JaredOfEuropa]

If documenting your technical procedures puts your job at risk, then you aren't the right things, to be valuable enough to your company in the first place.

Exactly. Also, do not forget that the best way to ensure you will never be promoted, is to make yourself indispensable at your current position. As all career counsellors will say: on any job, you should be training your replacement from day one.

Re:hire a Technical Writer

[Todd Knarr]

You'll never succeed at this. The Army has a test for officers in one of their advanced programs. The officer is given a mission and has to write out a set of orders for that mission. Those orders are then given to a unit to carry out, with one addition: the soldiers are to do their best to fail to carry out the assigned mission without disobeying those orders (technicalities are perfectly fine as long as no order is actually disobeyed). If the soldiers manage to fail to carry out the mission, the officer fails the test.

I believe this test has a completely unblemished record: no officer has ever managed to pass it.

Sometimes the fault does lie with the person carrying out the instructions. Every set of instructions assumes some minimum level of skill and/or intelligence from the person carrying them out. If you don't think so, remember that even a character-by-character walk-through of logging on assumes that the person knows to turn the computer on first. The instructions on how to turn it on assume that the computer's plugged in or the person knows where the cord and plug are and how to plug them in, and that either the instructions are written for one particular revision of a particular model of computer or the person knows how to find the power switch on an unfamiliar computer. I happen to have personal experience with just how bad it can get. Helpdesk call from one of our midwest truck stops, reporting that their pumps weren't working. It finally got escalated to me as the developer who wrote the pump-control software, since nobody on helpdesk could figure out why the pumps weren't responding. I went through a few basic checks, then told the manager to go out to the pump island, gave him a walk-through of the internal self-test of the pump, and asked him to run the self-test and tell me what codes it reported. His response: "I can't go out there. A tornado came through and tore the islands up, and the main electrical line's laying on the ground out there sparking.". Turns out that, besides the pumps being physically damaged, the power was completely down and the computers were running on UPS batteries. One would think that any reasonable person would've connected a tornado tearing the pumps half off the islands with the pumps suddenly failing to work correctly, but apparently not.

Re:the easier to edit the better

[skeptical_monster]

We are using mediawiki for this; it seems to work great, eventually someone catches stuff that has gotten outdated, and it is pretty easy to edit and track changes. The real problem is that search in mediawiki is just dreadful; the index they use is weird, word highlighting is weird, and search is very important for this kind of application of a wiki. So we have some pressure to move to something else. Personally, I'm looking for a wiki with decent search. Wikis are the perfect medium for internal documentation, you need everyone involved to braindump all the time, and it needs to be editable by others. In other words, it needs to be admin-free and grow organically.

Re:And When Technical Procedures==Scientific Metho

[billcopc]

I worked very briefly at Dell, doing corporate tech support (hardware), and well not to brag but I was still #1 in the stats ranking a month after I quit until my averages rolled off... anyway I spent much of my off-call time trying to figure out a way to condense my smarts and experience into easy-to-follow instructions for my neighbours, who were often struggling with what I considered very basic problems.

To put things into perspective, my average call time was 5 minutes. That includes the occasional hour-long clusterfuck, which means the great majority of my calls were under 5 minutes. The top 10 techs had averages in the 15-20 minute range, and most everyone else was 45 minutes and up. Well now what was I doing differently, besides being the guy with the most hands-on PC experience ? I was being lazy, that's what! And I was committed to sharing my lazy ways with the rest of the crew.

During the exercise. I learned a few things:

1. It is damned hard to put into words things that are trivial (to you)

2. Logic, much like common sense, is a rarity these days

3. Most people fail to factor in the true cost of support time

So for #1, I had a non-guru friend take instruction, helping me dumb things down and bridge the gaps until we both agreed he had mastered the situation. He would express his frustration at my poor instructions, and ask a zillion questions until I had a grasp of my own internal thought process, of things that I did automagically.

For #2, I ran through a large number of scenarios and wrote down my own inner thoughts at each decision point. At the end, I trimmed these down to a rather large, multiple-entry flowchart. The neat thing is it covered both specific problems like "my hard drive is dead" and fuzzy symptoms like "my screen is blank". You would start at the edge, identifying the main symptoms and then you followed the paths until they crossed. At the very middle was the final solution "Replace entire system", the catch-all in case no other endpoint was satisfactory.

For #3, I dug up details on the approximate cost of support time. This included salary, utilities, and amortized equipment cost. Then I made a list of common support resolutions and their total cost (parts, labour, shipping). This allowed me to show how a long call can actually be more costly than replacing the computer in its entirety, especially if the extensive troubleshooting still leads to component replacement.

So in the end, we had verbose instructions, a troubleshooting cheat-sheet, and a cost guide. It may have enabled incompetent techs to perform tolerably, but more importantly it gave everyone the tools to learn very quickly. After a week or two with these troubleshooting aids, many people had the common issues memorized and had developed strategies of their own.

That's what I consider a successful transfer of knowledge. Knowledge is much more than just static information, it's also the process to create more information.

Can't be done

[KGBear]

Not the way you're thinking. Where I work we use a wiki (mediawiki) and it works as well as any system I've seen, probably better than most. Now for the "can't be done" part:

Tasks like building a server, installing some software, connecting cables, etc., can and should be documented. Troubleshooting however cannot. Troubleshooting takes profound understanding of all the parts surrounding an issue and how they inter-operate; the ability to think long, hard and meaningfully; the ability to devise experiments, execute them, collect and analyze data and arrive at meaningful conclusions based on all that -- the scientific method, in other words. This is the kind of job that humans do better than machines and it is proverbially difficult to even understand, let alone document -- witness the "expert systems" of 20 years ago.

The big problem is that all non-technically-inclined people, including most people in management positions, think what we do is something mechanical akin to what plumbers do -- no offense to plumbers, who do things I can't do. From a user's point of view, "I can't print my e-mail message" is not much different from "I can't wash my dishes". Locating a clogged pipe and clearing it does require some technical skills and can certainly be documented. The e-mail printing problem however is several orders of magnitude more complex than that and, although it's probably possible to write a flowchart to document any possible thing that could be wrong in this scenario, it would be ludicrously huge, silly really. And that's talking only about day-to-day. If I'm really good at what I do I will design and implement systems so that errors of that sort are minimized. In other words, we're being asked to do the job of civil or hydraulic engineers on a plumber's salary.

There, of course, is the crux of the matter. Microsoft in particular, but the whole industry actually, are guilty of selling to managers the idea that this job can be done by drones, at all levels. Management is happy because drones don't cost much. Then, of course, drones are all they can get for what they offer.

What you want is knowledge, knowledge that can be provided by some, but by no means all, not even most, of the people who work for you. And you're tired of seeing those few good ones go away, leaving mostly drones behind. The only advice I can give you is: do document what can be documented. Make it a priority and make everybody responsible and accountable for documentation. But do acknowledge the really knowledgeable people in your team, treat them and pay them just as you would any other kind of expert. I know you're probably not in a position of paying your tech guru at orthodontist levels, but try to treat her at least as well as you do accountants.