How Do You Document Technical Procedures? 401
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."
Re:bad (Score:5, Insightful)
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 (Score:5, Insightful)
Make it simple, or you won't do it... (Score:5, Insightful)
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).
Document the situation specifics (Score:1, Insightful)
As an IT consultant, my approach to technical documentation is to document the specific configuration of a system. I specifically do not try to explain the product that I am documenting, but the configuration that I have given the product. For example, I would document the non-default installation options and the non-default configuration changes that I make after installation. Then, I will include in an appendix some links to internet articles/pages that explain generic concepts of the software product I am implementing.
In other words, I assume the reader is technically competent on the product, but needs to know how the product is configured in the specific situation.
Keep in mind, my audience is usually IT staff, so this may not be an appropriate approach for end-user type of documentation. That is more difficult, because there technical savvy cannot always be assumed. (IT staff members' technical competence cannot always be assumed, either, but IMO you cannot/shouldn't try to "teach" them a product through situation-specific documentation.
Not only do I know what you need... (Score:5, Insightful)
but I can be bought.
You need a competent process engineer, and good ones are expensive. Bad ones are a dime a dozen, and will drive your costs up by insisting, for example, that every procedure be a documented procedure, that every process needs to be flowcharted, that there's a distinction between a process and the document describing the process, or that the fiction that is RACI is not reducible to a single directive: "accountable".
This is, as they say, job security for the process engineers because they're constantly chasing a moving target. Also, the instant employees realize or suspect that they're being made interchangeable by participating in any process engineering effort, they'll learn to conceal key details which will make all work to date useless.
Organizations that don't realize that have chosen the way of pain. Yours is probably one of them.
Re:bad (Score:5, Insightful)
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:
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.
There are degrees for this (Score:5, Insightful)
hire a Technical Writer (Score:5, Insightful)
I can't stress this enough. There are professionals who have post-graduate education and vast experience documenting and communicating technical procedures. Hire one of these people.
If you don't hire a technical writer you will face all kinds of problems. You'll have technical people with poor English skills writing incomplete directions because they make assumptions about what the reader knows. You'll have 50 manuals with 50 different writing styles. You'll have 10 instructions in one sentence with no commas. You'll have unfortunate typos and grammatical errors which change the meaning of the sentence.
Technical writers are both technical and writers. Hire one (and not the cheapest one you can find) to do the job right and chock the expense up to preventive maintenance. The alternatives are putting faith in poor documentation and, in the best case, spending needless cycles working out the kinks, or, in the worst case, spending needless money on a settlement to your injured customers because your staff were improperly trained.
MediaWiki + job swapping (Score:3, Insightful)
Re:bad (Score:5, Insightful)
True, but the easiest way to get a raise/promotion is to change companies.
Re:Text document (Score:5, Insightful)
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.
Comment removed (Score:5, Insightful)
Re:bad (Score:2, Insightful)
Re:bad (Score:5, Insightful)
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 (Score:5, Insightful)
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!
Asked to document how I Program (Score:3, Insightful)
There's no Magic Bullet. Just get things written. (Score:3, Insightful)
Now, that being said, I tend to mix procedure docs with configuration docs. You can try to keep those seperate but it's often easier to combine the two. So, say you have a thin client system set up, you can have one doc that documents how the system is configured and how to perform basic tasks.
You don't need to get too detailed, of course. The intended audience isn't a non-technical user. Each document should have a few basic sections; Revision history, purpose, intended audience, and a simple explaination of terms such as for certian acronyms used. It's also useful to include software versions so you know what version of the software the document was written for. As you upgrade the softwasre, update the doc and update the software version.
Create a document template and with pre-formatted styles. That way, you cab bust out organized documents that all look the same and every one will automatically get things like a TOC based on your styles. It's worth putting in effort here.
In the end, though, just get as much information as possible down on "paper" and then work on making it accessable. I'd rather have to hunt for that IP address or login to a web site than to not have it at all.
And remember, it's not your job to provide TRAINING materials to people in the form of this documentation. (unless it IS your job, but it doesn't sound like it.) Your job is to make sure that the systems stay running and if something should happen to you, the company isn't screwed because the systems are documented. Perhaps more importantly, if a server you worked on a year ago crashes, you'll have all the information you need to fix it.
Anyone that thinks Documentation might lead to their dismissal because "We don't need him anymore" is dead wrong. If you write documentation, you'll be the most loved person in all of IT in your company.
Re:bad (Score:5, Insightful)
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?
Re:bad (Score:4, Insightful)
1. Your company is less likely to send managerial positions over seas.
2. At age 40, you should have aquired experience that makes your time more valuable than gold.
3. If you're in a managerial position, being fully trained on new technology is not necessary. You only need to know enough to properly manage your associates.
4. New college graduates do not have the experience needed to effectively and efficiently manage.
5. Ok, so you can't do too much about absurd deadline demands. This is not unique to IT by any means. But with higher levels of experience comes more bargaining power.
Re:bad (Score:5, Insightful)
He then leverages you into a cushy advisor role, and you advice to make him a board member.
He makes you advisor to the board. You advice to make him VP.
Get the picture? Been there, done exactly that. We make a mean, lean, promoting machine!
What is this document word you speak of? (Score:3, Insightful)
Must be some kind of new-fangled term out there....haven't heard it or seen it really much out in the work place...
Seriously, I actually have RARELY seen it in the tech end of things. On projects I'm on, you have those people doing risks, and other paper pusher jobs doing all kinds of documentation, but, I rarely see much of any kind of good documentation in the tech end of things. I'm talking big projects, govt. projects...etc.
For instance now, working on a gig to take over a number of database instances....I didn't even really get a list of what databases instances are even OUT in the environment, much less how each was set up, etc. Hell, took me weeks to find someone who had the oracle OS user password.
I'm currently documenting stuff, but, I don't find it that unusual to come into a job, and in the tech area actually have very little documents and procedures. I always hear about people out there going through and heavily documenting things and processes, like naming standards....but, very rarely have seen it in real life practice.
Re:Make it simple, or you won't do it... (Score:5, Insightful)
Getting your average wiki up and running from scratch should be pretty simple:
Version control, edit history, and ease of connecting documents make wikis vastly superior to a directory full of Microsoft Word documents.
Re:bad (Score:3, Insightful)
....is to change companies.
Its a well known phenomenon is that the company changes you before you have a chance to change companies
Apologies for the unintentional 'In Soviet Russia' nature of the post.
Re:bad (Score:4, Insightful)
When I need mod points, they are no where to be found. Your comments are exactly what I am trying to do where I work (government agency which makes it even more difficult).
Everything that needs to be documented is written down and saved in a specific location (Procedures) so anyone can go there and see the exact step-by-step procedures which need to be done to install and configure software, who to contact for X problem which is handled outside the agency, screenshots, and anything else that may come up. Especially those once-a-year happenings which no one can remember how to resolve from the previous time.
We still have a mainframe which, supposedly, is to be used to update patch panels, wiring schemes, etc, but which isn't remotely up-to-date, so instead, I've taken the initiative to create a spreadsheet with a tab for each switch documenting cable numbers and what is on them. Needless to say, this involves cleaning up the mess the guy who is as organized as a rabid wombat has created because he's too lazy to do things the right way and then swears off when you tell him he needs to update the file (Naw, I don't use the spreadsheet. [You don't use the mainframe file either moron]).
Your final words are the exact phrase I use when I tell people who have solved a problem. Write it down! Don't let us guess at the answer.
Yeah, I know, preaching to the choir. It's not as if employers want someone who can get the job done, correctly, on time and fully documentated so they know what's what.
Re:bad (Score:3, Insightful)
2. At age 40, you should have aquired experience that makes your time more valuable than gold.
Hahahaha. No. Most folks stay in tech and do nothing else. In the meantime, their management experience is nothing.
"Should". Who says? You? So what you're saying is, staying in tech is worthless? Experience in the tech world is meaningless. I have plenty of experience with distributed applications design, but now, who needs it when you can get an SOA app that does exactly what I used to develop - from scratch.
No sir. Experience only gets you so far in this industry.
You are replaceable - no exceptions.
Re:bad (Score:2, Insightful)
If everyone who enters IT is expecting to become a manager, I suppose that explains the excess chain of managment found in many companies.
But it is likely to figure out that it's got a surfeit of over-paid do-nothings gumming up the works.
Sure - experience in your field. Two decades of experience as a developer no more necessarily makes you an expert manager than two decades as a beat cop qualifies you for a seat on the city council.
Managers need broad rather than deep training, but still need constant updating.
And yet they put novice MBA graduates in charge of seasoned productive people.
Re:bad (Score:4, Insightful)
Also, if nobody else can do your job, it can be a PITA scheduling vacations.
Re:What is this document word you speak of? (Score:5, Insightful)
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.
Re:bad (Score:3, Insightful)
Amen to that. I actually won a bonus one year because I make it a point to teach ANYONE who wants to learn how to do what I do. My entire goal in my career here is to learn something, then as fast as a learn it, teach it to someone else.
The problem is that nobody ever wants to take the job completely, so I still have a whole bunch of little crappy jobs floating around that I'm more or less in charge of. However, as fast as they pop up, my manager yells at people to take them off my plate. (It's nice having a supportive manager.)
Re:Make it simple, or you won't do it... (Score:3, Insightful)
Umm. What you recommend is far more complex to keep up to date than a wiki, my friend. Templates? Word Processors? With a TOC???? What?
A wiki gives you:
- Version Control
- Shared Contributions, and ACLs
- Fast, easy editing
- Simple, fast, consistent markup and presentation
- Automatic indexing and linking
Word docs? Are you serious?
Re:bad (Score:1, Insightful)
True, but the easiest way to get a raise/promotion is to change companies.
Easy doesn't always mean that it is a good idea. Sometimes having loyalty to a company (rather than job changing every 2 years) is the best thing for your career.
Re:hire a Technical Writer (Score:3, Insightful)
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.
So true. One of our offices called in, saying the computer wasn't working. In the background I could hear the UPS screaming its battery-all-but-dead alarm. I asked if they had checked the circuit breaker, because it sounded like the UPS was not getting power. They replied that the power was out, and had been for almost an hour. I guess they thought that a UPS was Three Mile Island In A Box. Anyway, there was shutdown software on the computer, but it did not work because they had disconnected the UPS monitor cable (the software would not start if it could not see the UPS). Why had they done this? Well, they had no choice. Every time the power went out, the software would shut down the computer! (/indignant_tone_of_voice) Of course. Where was my head at?
The old saw about them making better idiots is true
Hey, nice reality check. (Score:4, Insightful)
You saved me some typing!
The older they were, the better they were built.
This is because of the building code.
Today, builders build to code, and the code specifies bare minimum safe method. As new techniques are developed to cut costs, the code is modified to allow cheaper, less redundant methods.
Before the code, builders built in competition with each other. They tried to build better houses, so they would have better reputation, so they could charge more.
But now, they just build to code. Full stop.
There's a place near me in PA that has no building code. All the buildings there are fundamentally stronger and better, no lie.
I try to apply this to programming. If a programmer doesn't write code good enough to stand without external documentation, I find another programmer.
Re:What is this document word you speak of? (Score:3, Insightful)
Lack of documentation is so bad that many people won't read the documentation I write. They just aren't used to working that way.
It's a cultural thing, though. Some cultures are better than others. Java is WONDERFUL -- Java developers pretty much accept that missing or incomplete Javadoc in a public API is a serious bug. C and C++ are pretty pathetic. There are many extremely well-done and well-polished C and C++ libraries that have copious but holey documentation. You can tell the developers spent a lot of time working on the documentation but didn't really know how to do it -- probably because they've never bothered using documentation themselves. Typical documentation deficiences include:
Re:bad (Score:3, Insightful)
Re:bad (Score:4, Insightful)
I've had a bit of experience with this, so I'll chime in...
The first thing to do is determine the precise audience for the documentation. Is it your peers for use in operations? Is it for managers or other process owners to keep track of processes and procedures? Once you have that figured out, you can determine the minimum level of knowledge/experience/etc that the audience is supposed to have (assuming the reader is qualified and competent in the position they hold). The purpose to this is to set boundaries on the level of detail you need to provide. Assuming no boundaries at all is a mistake and your documentation project will fail.
The next step is to outline the items that need covering. I stress the term outline. That outline should be written by those with as much experience/knowledge/etc as needed to give a high-level overview of the process. One outline should be made per process and should also be maintained in some sort of version control system.
THEN you begin writing the documentation. I typically write up step-by-step guides for people with a little bit of knowledge and absolutely no experience, so you might want to try starting with something similar and go from there. Remember to include as much or as little detail as required by the intended audience. Again, these documents should be written by those with enough knowledge and experience to perform the functions being documented and should also be maintained in a version control system. Additionally, these documents should be reviewed regularly for accuracy and relevancy, so some sort of time-out mechanism would be good, too. Lastly, someone needs to approve final drafts before they're added to the repository (which is a whole separate process that should be documented, giving rise to a chicken-and-egg problem).
As a final note, it's much more difficult to start writing something from scratch than it is to modify an existing document. Buckle down and start somewhere. First drafts are almost always going to suck (ask any professional or amateur author). Accept those facts and you'll feel much better.
Re:Hey, nice reality check. (Score:4, Insightful)
Yes, private homes may have been better built before building codes, because the occupants had a direct interest in making the home safe. However, commercial buildings (like the Triangle Shirtwaist Factory [en.wikipedia.org]) are not subject to the same restrictions. There are numerous examples (U.S. in the 1800s, third world countries today) where the lack of adequate building codes allows builders to get away with murder (quite literally, since their buildings often kill people when they collapse).
Yes, I agree that the phenomenon of building "to code and not a whit more" isn't ideal. However, I'd argue that its better than the preceding practice of building as cheaply as possible, safety of the occupants be damned.