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

Knowledge Management

[Linker3000]

Look up 'Knowledge Management' as a starter.

We have most procedures documented step-by-step on what we call 'one page guides' (OPGs) - in other words, if you cannot document a procedure on two sides of paper then it's too complex and needs to be broken down further.

The OPG form is a standard template in Word. having a common format ensures that people can scan through OPGs and know exactly where to look forthe details they want. The OPGs have sections as follows/EG:

TITLE: How to Reset a Draytek Router to Factory Defaults

Scope: Comms

Description/Symptoms: A router may need to be reset when....

Action/Procedure:

1.
2.
etc.
*end*

We don't use flowcharts as it takes too long to create maintain them. Simple, stepped, lists in your favourite word processor are easy to amend quickly.

We have 6 categories of OPGs (because that suits our needs: Hardware, Software, Comms etc.) and each staff member has the 'top 10' OPGs for each category in a folder on their desk for reference. We do have them online, but paper copies are easier to search through when you are not near a computer. All other OPGs are also held online and in SOP folders in the work area.

Issues such as 'Look for valid traffic on the monitoring interface' are handled exactly as you describe - by refrence to another OPG - so staff can check them out if needed.

The Knowledge Management aspect ensures every OPG has an owner responsible for its maintenance, plus there's a submission, validation and approval process. It's a bit like hard work to setup, but once you get organised, doing it properly from day-one pays dividends.