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

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.

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.

Monkey Directions

[SeanGilman]

That's what we call it. We write up a set of directions so simple even a monkey could follow. We include screen shots at just about every step so the user can see what it looks like. Currently we have them in a mass collection of Word documents spread over a bunch of network drives. Yea, it sucks to find a particular direction document.

We are in the process of loading all of our monkey directions into a wiki. That may work for you. You could create pages that have the high level overview directions for the users that know what is what and then have each direction link off to another wiki page that has more detail.

No matter what direction or option you find one thing you need to keep in mind is the more simplistic you make your directions the harder it is to keep them up to date.

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: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.

Re:WFD

[Clover_Kicker]

The disadvantage is that you've generated read-only documents.

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

[nine-times]

I would recommend NOT using any special software like a wiki for your primary documentation. It should be simple and printable

A wiki can be simple and printable.

I agree though that part of getting other people organized is acknowledging that they may have different methods and tools that work better for them. Sometimes it's helpful to let people write up their notes and changes however works best for them, but make sure they set aside times to enter those notes into whatever constitutes your central repository. Whether or not your repository is a wiki, you should try to have some kind of change management so you're keeping a history.

ISO Requirements

[Bullfish]

Actually, if your workplace is ISO certified, it would have had to document procedures and work instructions to get and maintain the certification. A procedure contains high level information, while a work instruction actually documents what steps it takes to do the job. The one thing ISO does is force (theoretically) a company to do what they say they are supposed to be doing, the other thing is does is generate tons of documentation. It just goes with the territory if you want the cert.

Re:bad

[Mr. Slippery]

Clean, clear code is the best documentation.

Bullshit.

Let me say that again, with appropriate emphasis:

BULLSHIT.

Code does not document itself. It does not document what considerations went into design. It does not document asssumptions about user behavior or desires. It does not tell you how this module fits with others. It does not give you an pre- or post-conditions of a function or method. The very idea of "self-documenting code" breaks the encapsulation and abstraction that are necessary to build large software projects.

Any software developer who believes in self-documenting code needs to be drummed out of their profession the same way that a dentist who believes in the Tooth Fairy would be.