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

bad

[tritonman]

Documenting technical procedures is bad for job security.

Re:bad

[D Ninja]

No. No no no no. Wrong. [RED FLASHING LIGHTS]

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. I would even venture that you don't know what you're doing that you can't sustain your career on your skills alone and have to use methods like this to maintain your employment.

This idea of "write crappy code" "no commenting" "don't document" and other ideas is what causes half of the issues that I deal with on a day-to-day basis. I would keep around someone who does the top three far before I would keep around someone who tries to maintain their job by making them the only one who can perform their job.

(Alright...rant off. I get really upset by this type of thinking.)

Re:bad

[jetsci]

Its also bad when 4 years into your position you forget what service X does and you can't get it up and running after a major failure because you failed to document it.

Re:bad

[ChadDa3mon]

I think you misunderstood what I'm saying. I'm not documenting this for 'my' job, nor am I worried about my job security. I am trying to write documentation for 150 people around the world to follow so that we're all doing things the same way.

Re:bad

[Samschnooks]

I would even venture that you don't know what you're doing that you can't sustain your career on your skills alone and have to use methods like this to maintain your employment.

Wait till:

1. Your company decides to send the work you're doing overseas.
2. You get over 40.
3. Your company decides that it is switching technology and is unwilling to train you.
4. Your company decides that it needs new college graduates because they are the ones that are up to date with current technology.
5. You burn out after having to work 60 hours a week for several years straight. Not necessarily because you have to, but because the bosses equate time in the office with amount of work and the fact that they always give unreasonable deadlines.

You will change your tune.

Other than that, I agree with you. Competing in the Global economy, especially in IT, is extremely difficult and competitive. I don't care what you do or how good you are, one day, you will lose out to cheaper folks overseas - exception: defence work. It is inevitable.

Re:bad

[Clover_Kicker]

True, but the easiest way to get a raise/promotion is to change companies.

Re:bad

[dintech]

Absolutely. Sometimes you can even come back to your old company a year later to the salary and position you should have had anyway.

Re:bad

[axafg00b]

True story - I start my new job as Network Team Lead with one cabling tech and one temporary consultant hired to fill in after the rest of the network team resigned. My documentation? Six large moving boxes full of c**p from the previous two leads and their managers. No online docu, no drawings, and a whole lot of head-scratching. This lead to us scrapping a major disaster recovery test because it was based on a network that had been dismantled two years prior, and no one had bothered to maintain the documentation. Yes, the company was in bad shape, but it was improving. By the time I left four years later (after a merger with a larger firm who did not require my services) we knew down to the specific patch cable where things were, and what processes we needed for hardware/software configuration.

Write it down!

Re:bad

[nine-times]

Also, do not forget that the best way to ensure you will never be promoted, is to make yourself indispensable at your current position.

This is an excellent point. I've found the best way to get promoted, in fact, can be to eliminate the need for your current position entirely. It's counter-intuitive, but it can work out

Imagine you're paying someone a full-time salary, and they take the initiative to figure out how organize everything such that, instead of working 40 hours a week, he's getting the same amount done only working 2 hours a week. And then he comes to you, tells you this.

Now, are you really going to say, "Your position isn't necessary anymore, so you're fired."? Or might you possibly think that he's a helpful guy and decide to put all his new free time to good use?

Text document

[tsa]

I just use a text document with point-for-point descritions on how to follow the procedure. It's practical because you can print it and take it to the workfloor and cross the points you've finished. When you find out something new you can easily write it on the paper and add it in the computer file later on. Just make sure there is only one person maintaining the file, to avoid chaos and misunderstandings.

Re:Text document

[indytx]

I just use a text document with point-for-point descritions on how to follow the procedure. It's practical because you can print it and take it to the workfloor and cross the points you've finished. When you find out something new you can easily write it on the paper and add it in the computer file later on. Just make sure there is only one person maintaining the file, to avoid chaos and misunderstandings.

This actually works quite well in a number of settings. Checklists work. Years ago, when I was working through college at a warehouse, I had a job of some responsibility that usually involved me working late nights. Eventually, my boss quit and I was left in charge. To take a night off, and make sure the wheels didn't fall off, I created a text file with a checklist of the nightly procedures. Not only did it force me to think about everything I did, it also helped everyone know how much longer we would have to work each night before we could call it a night. You would be surprised at how much morale can improve if everyone has an idea of what's going on. Managers making decisions, seemingly arbitrarily, don't instill much confidence.

My advice would be to document your procedures, what you actually think needs to be done, and then take some time to distill them into a list. Then, following the list, does the procedure accomplish the task? If yes then move on to the next task.

Folding + Wiki might get you closer

[Red Storm]

I was reading through some of the Trac hacks for the wiki component and they had a folding plugin. If you create a table of steps you could then create a "fold" with greater detail should someone want to open it up and see it. The nice thing is you are not taken to a new page and you can continue to work and read the page you are already on. You can also imbed folds which can also allow a user to drill down to as much or as little detail as is needed or available.

All that is left now is to write enough information for the lowest common denominator.

Make it simple, or you won't do it...

[eth1]

Whatever you do, make sure the process for creating and updating the documents is simple, or it'll quickly become out of date and useless.

I would recommend NOT using any special software like a wiki for your primary documentation. It should be simple and printable, and not need a special server set up to access/use your docs in case of a disaster recovery situation.

Create a template document. If you use a word processor, set up standard formatting styles for sections, TOC, etc, so the docs are easy to create and navigate.

Put enough detail in the document so that you can hand it to a marketing droid and have them successfully complete the procedure. You'll be glad you did when you're stressed and under pressure from the Big Boss in an emergency (or if the whole IT department keels over from a tainted batch of Mt. Dew, and the only people left are completely unfamiliar with your environment).

Re:the easier to edit the better

[JCSoRocks]

A wiki is perfect for this. You can write simple step-by-step instructions for the more experienced techs. Within those you can easily integrate links explaining processes and terminology that aren't understood by the new guys. You also get the free benefit of searchable change tracking. You're not going to get that from a text file or a visio document.

There are degrees for this

[ktappe]

Speaking as someone who has a degree in technical writing, your question is symptomatic of the entire industry's attitude toward (read: lack of respect for) technical writing. You hire people with degrees to run your networks and program your computers and execute your business processes, so why are you not hiring someone with a degree to do your technical writing? It's a specific skill that most people do not have and those who do it have had to study and learn. Realize that and you'll be better off. [/rant]

Comment removed

[account_deleted]

Comment removed based on user account deletion

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.

Re:What is this document word you speak of?

[jbengt]

Being a mechanical engineer in the construction industry (what's left of it, anyway) I would be willing to bet that the way builders build buildings is not much better than the way programmers write programs.

Code plan review and building inspections largely consist of filling out forms, having an architect/engineer/contractor's signature in the appropriate places, adding statements that some particular part of the code is being followed, along with a generous helping of checks to see that more or less arbitrary rules are enforced, and the occasional check to see that the numbers add up. Of course, structural designs for high rises may get a more useful review compared to architectural review of a one-story strip mall using typical designs.

While building codes are no subsitute for good design, they're (bad analogy coming) like the documentation for a programming language - if you don't follow them, you won't be able to build your project.

One final point, before I get too cynical, poor documentation is not just found in code, one of the most common weaknesses of blueprints is poor documentation.