Beta

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

How Do You Document Technical Procedures?

timothy posted more than 5 years ago | from the mt-spokane-ski-patrol dept.

Businesses 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."

cancel ×

401 comments

Sorry! There are no comments related to the filter you selected.

bad (5, Funny)

tritonman (998572) | more than 5 years ago | (#26918055)

Documenting technical procedures is bad for job security.

Re:bad (5, Insightful)

D Ninja (825055) | more than 5 years ago | (#26918159)

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 (1)

ColdWetDog (752185) | more than 5 years ago | (#26918223)

Sorry, OP is a bad, bad person for not including tags.

Re:bad (1)

ColdWetDog (752185) | more than 5 years ago | (#26918259)

Uh, let's try ** sarcasm ** tags this time. Stupid slashcode.

Re:bad (5, Informative)

ChadDa3mon (642255) | more than 5 years ago | (#26918273)

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 (1)

jetsci (1470207) | more than 5 years ago | (#26918399)

What about just using a wiki with enforced layout standards? Where I work(big government bureaucracy) we use DocOpen(Windows shop...*sigh*) and just enforce standards through strict approval policies...

Re:bad (4, Interesting)

JaredOfEuropa (526365) | more than 5 years ago | (#26918277)

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:bad (5, Insightful)

Clover_Kicker (20761) | more than 5 years ago | (#26918381)

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

Re:bad (5, Insightful)

dintech (998802) | more than 5 years ago | (#26918669)

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 (4, Funny)

DrLang21 (900992) | more than 5 years ago | (#26918969)

I used to work at a company where this was a standard career advancement strategy.

Re:bad (5, Insightful)

nine-times (778537) | more than 5 years ago | (#26918893)

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?

Mod Parent Up. Smack the GP. Re:bad (0)

Anonymous Coward | more than 5 years ago | (#26918317)

I have to second this. Having done an honest job of trying to leave good foot prints behind, and having to follow the footsteps of someone who follows the GP's philosophy, I submit that the GP and their ilk should be put aboard the Lawyers, Actors and Politicians shuttle and launched into space.

Re:Mod Parent Up. Smack the GP. Re:bad (1)

dintech (998802) | more than 5 years ago | (#26918705)

Too expensive - we're in a recession you know. I prefer the 'deep ocean explorer' route. Meaning put them all in a shipping container and drop it over the side. You can put windows in it if you must.

Re:Mod Parent Up. Smack the GP. Re:bad (1)

telchine (719345) | more than 5 years ago | (#26918975)

I have to second this. Having done an honest job of trying to leave good foot prints behind,

Yah, thanks for that it made it so much easier for me to do your job after I back stabbed you and got you fired. How's the unemployed life treatin' ya?

Re:bad (5, Insightful)

Samschnooks (1415697) | more than 5 years ago | (#26918335)

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 (3, Insightful)

DrLang21 (900992) | more than 5 years ago | (#26919101)

This is why you should always have your eye on a higher position and be formulating a plan to get there. This partially resolves several problems.

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 (1)

evilkasper (1292798) | more than 5 years ago | (#26918391)

I'm glad somebody beat me to this rant, documentation is your friend. As such I'll just offer up what I do; keep it simple as possible. If a word doc with bullets suffices do that. You can always link to other documents for further explanation when needed.

Re:bad (1)

internerdj (1319281) | more than 5 years ago | (#26918829)

To further that sentiment, my principle (ignoring for the moment the documentation requirements of any particular employer) is:
1) Document in the code
2) If you can't convey meaning through the code naming conventions, Document in the comments
3) If you can't convey meaning through a comment without taking up the entire screen, reference a diagram
4) If you can't simply and completely convey the information with a diagram, write it in a document
5) If you can't define it in a document, it is time to go back to earlier phases, like requirements, analysis, or design.
Obviously this list would be different if I didn't write code for a living, but I'd still use the simplest way possible to document my work and still convey meaning.

And When Technical Procedures==Scientific Method? (5, Insightful)

Alaren (682568) | more than 5 years ago | (#26918475)

When I was the Desktop Support Supervisor at GoDaddy, I was asked to write some "SOPs." My team was kind of the "dumping point" for any non-network technical task (and a handful of local network tasks like lighting ports).

A lot of the stuff I wrote was strictly software licensing procedures--which spreadsheets to fill out, who to get spending approval from, that sort of thing.

But the technical procedures were a completely different story. My boss was constantly suggesting "a wiki or something" on the intranet documenting fixes for various problems. Although I had a pretty secure position, my subordinates were often treated as expendable by company executives, so we spent a lot of time training new guys, and when an old guy left (or was thrown out, though not by me!), I lost a lot more than just a good worker.

What I could never get through to my boss was that the "SOP" for troubleshooting desktop problems is a combination of general knowledge, intuition, and the scientific method. Some things can be documented--POST beep codes, for example--but usually those things are already documented all over the internet and in the manufacturer's literature as well. A lot of the job was knowing how to accurately describe symptoms to Google and finding someone else who had fixed the problem before. Occasionally a really weird problem required patiently swapping out parts or drivers until the problem went away.

But where do you start? How long do you spend at each level? At what point does replacing the computer or re-imaging the drive become more efficient than actual troubleshooting? And how do you document basic deductive reasoning and process-of-elimination thinking?

In other words, when you say "we have to document every procedure and process, no matter how mundane or 'common sense' it may seem," you've already lost. You don't need meticulously documented procedures, you need to take those "varying degrees of technical competency" and educate them to a higher level of competency.

I don't think this is the same thing as not commenting your code or documenting bureaucratic job functions. But "technical procedures" aren't like mindless assembly-line procedures. The better you understand the process--the greater your technical competence--the better you will do your job.

Re:bad (0)

Anonymous Coward | more than 5 years ago | (#26918717)

LOLOL

Hook.

Line.

And the whole sinker.

Boom.

Re:bad (0)

Anonymous Coward | more than 5 years ago | (#26918859)

likewise... I worked one summer taking over a website from a past hireling and ended up wasting so much time because of awful documentation, I'm sure my boss would have prefered it being well commented so I could have done more work

Re:bad (1)

religious freak (1005821) | more than 5 years ago | (#26918179)

If your job relies on you knowing only current information and not the ability to apply it to new situations, odds are your job isn't secure to begin with.

Re:bad (5, Insightful)

jetsci (1470207) | more than 5 years ago | (#26918215)

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 (1)

jabjoe (1042100) | more than 5 years ago | (#26918559)

Clean, clear code is the best documentation.

Why write everything twice? The text version always falls out of date anyway.

http://source.winehq.org/ [winehq.org] is the best Win32 documentation I know (providing what you are after has been implemented).

Re:bad (2, Insightful)

jetsci (1470207) | more than 5 years ago | (#26918599)

Are you telling me you code very server you work with from scratch? I certainly don't. Documentation as a rule of thumb is good practice because it saves me time having to dig through code trying to link everything up. I don't want to have to watch a server to figure out the intricacies of its daily running. Give me a 2 page brief and I'm up and running. That's how it should be.

Re:bad (-1, Troll)

Anonymous Coward | more than 5 years ago | (#26918345)

Psycho Killer
Qu'est-ce que c'est?
fa fa fa fa fa fa fa fa fa fa better
Run run run run run run run away
OH OH OH

Re:bad (1, Funny)

Anonymous Coward | more than 5 years ago | (#26918571)

You're talking a lot, but you're not saying anything.

Re:bad (0)

Anonymous Coward | more than 5 years ago | (#26918653)

I use a local copy of Wordpress for all my documentation. No one has access or knows about it but me. This keeps my job secure and also reminds me how to do those complex tasks which are only done once or twice a year.

Re:bad (5, Insightful)

axafg00b (398439) | more than 5 years ago | (#26918691)

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 (1)

wsanders (114993) | more than 5 years ago | (#26918729)

Thank you Terry Childs.

Text document (5, Informative)

tsa (15680) | more than 5 years ago | (#26918167)

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.

"and add it in the computer file later on" (2, Interesting)

brouski (827510) | more than 5 years ago | (#26918271)

That's always the catch, isn't it? I'm sure we've all seen the printed instructions with more handwritten addendums and notes in the margins then there is printed text.

Re:Text document (5, Insightful)

indytx (825419) | more than 5 years ago | (#26918415)

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.

Re:Text document (1)

Thelasko (1196535) | more than 5 years ago | (#26918715)

As a former process engineer, I couldn't disagree more. Granted, I work in hardware, not software. A text document is the worst way to communicate to someone without technical knowledge.

Personally, I use as many pictures as possible. A picture can explain something faster and more effectively than any amount of text. Sure, it may take you longer to write, but it will take a lot less time to read. Think about how many people will read this document. How many man hours will you waste reading your document? How does this compare to the amount of time it takes you to add pictures?

I've found that presentation software, like PowerPoint, works best for this. Presentation software usually has all of the tools to manage pictures and add other shapes (arrows, boxes, etc.) to get your point across. Unfortunately, most presentation software isn't printer friendly, so a word processor may be required.

Re:Text document (1)

tsa (15680) | more than 5 years ago | (#26918775)

There's nothing against adding pictures to the text document.

Re:Text document (1)

tsa (15680) | more than 5 years ago | (#26918863)

I see where the problem lies now. With 'text document' I did not mean an ASCII file, but a document that contains text. It can be made using a word processor like OpenOffice. Adding pictures is no problem. I also add as many pictures as I feel is necessary.

the easier to edit the better (2, Interesting)

Clover_Kicker (20761) | more than 5 years ago | (#26918177)

If there's a mistake or something in your docs are unclear, you want the guy using the docs to be able to fix it right on the spot. For that reason use a wiki, no-one is going to fire up Visio or whatever and diddle a flow char tin the middle of a call.

I assume the people using it are phone monkeys, make sure to track who makes improvements so that it doesn't penalize the guy who takes a minute to fix something but then their talk time suffers and they get bitched at.

Re:the easier to edit the better (5, Informative)

JCSoRocks (1142053) | more than 5 years ago | (#26918279)

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:the easier to edit the better (1)

evilkasper (1292798) | more than 5 years ago | (#26918481)

I would think instead of having the users edit the actual working process documentation, that they should rather be able to submit a revision. If anybody can make changes to it, you may as well not have it. Your process will lose it's integrity because some moe thinks that step 2b isn't necessary.

Re:the easier to edit the better (1)

Clover_Kicker (20761) | more than 5 years ago | (#26918577)

Wikis track who made changes, if someone is actually making harmful changes it won't take long to find out who and have a chat with their boss.

There's a balance I suppose, but I lean hard towards "trust the guys doing the work to easily change the documentation".

Folding + Wiki might get you closer (5, Informative)

Red Storm (4772) | more than 5 years ago | (#26918181)

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.

Re:Folding + Wiki might get you closer (1)

anomalous cohort (704239) | more than 5 years ago | (#26918257)

I agree. Get thee to a wiki [stackoverflow.com] .

Agreed....perfect application for a wiki (0, Redundant)

TrueJim (107565) | more than 5 years ago | (#26918503)

Wikis are great for this.

Re:Folding + Wiki might get you closer (1)

nine-times (778537) | more than 5 years ago | (#26918961)

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.

That actually sounds terrific. Does anyone have additional information about whether pluglins like this are available for other wikis?

For server provisioning... (2)

tcopeland (32225) | more than 5 years ago | (#26918185)

...I usually start with documenting the configuration on a Wiki (or a file in a Subversion repository somewhere) and then shift things over to Puppet [reductivelabs.com] when I get the chance. The nice thing about the latter is that you know all the setup specifications are correct since that's what's actually being applied to the servers.

Documentation of system provisioning is just one small part of the question you're asking, but hopefully that helps.

Monkey Directions (2, Informative)

SeanGilman (1083559) | more than 5 years ago | (#26918233)

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.

Make it simple, or you won't do it... (5, Insightful)

eth1 (94901) | more than 5 years ago | (#26918239)

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:Make it simple, or you won't do it... (0)

jellomizer (103300) | more than 5 years ago | (#26918395)

Lookup and study UML.
Its MBA approved and actually useful for people who are slightly non technical and useful for the technical alike.

Wiki is simple and Printable Re:Make it simple. (1)

Anonymous Coward | more than 5 years ago | (#26918471)

Wiki would still work for this. Most wiki's come with a printer friendly css style sheet so that printing an article looks nice and doesn't waste paper with menus et al.

In response to the first response:
Is there some kind of Wiki that does UML? Or a UML engine based on a Wiki? That'd be awesome.

----
Captcha Text of Irony: obscurer

Document the situation specifics (1, Insightful)

Anonymous Coward | more than 5 years ago | (#26918249)

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.

Re:Document the situation specifics (1)

Tranzistors (1180307) | more than 5 years ago | (#26918813)

With IT staff, you can always send them to read the friendly manual form software vendor. If the vendor has great documentation, why duplicate it?
I've noticed that free software usually has great documentation.

WFD (1)

Marxist Hacker 42 (638312) | more than 5 years ago | (#26918251)

Looks like an obvious use for a Work Flow Diagram- you can do it in Visio as a flow chart with "page links", but then the user would have to have Visio to actually read the document. I suspect it could be done in HTML also.

Re:WFD (1)

OG (15008) | more than 5 years ago | (#26918321)

Visio will export to HTML with working hyperlinks, thus getting rid of the need for end-user Visio installs. A Visio/wiki combination sounds like a good option for this particular idea.

Re:WFD (2, Informative)

Clover_Kicker (20761) | more than 5 years ago | (#26918405)

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

I maintain (1)

drolli (522659) | more than 5 years ago | (#26918255)

a consistent quality between my documentation of technical procedures and my source code.

HTML? (1)

novalis112 (1216168) | more than 5 years ago | (#26918287)

What's wrong with documenting your procedures using...... a *document*? Okay, get fancy and make it an *HTML* document.

If you want to use a wiki, I've been happy with dokuwiki.

Not only do I know what you need... (4, Insightful)

gr3y (549124) | more than 5 years ago | (#26918299)

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.

every click and keystroke (1)

prgrmr (568806) | more than 5 years ago | (#26918301)

Use your favorite text editor or word processor and document every mouse click and/or keystroke. Using script to record a command-line session (when available) to use as a basis for your document can be a huge time-saver.

Know your Audience (1)

jimicus (737525) | more than 5 years ago | (#26918359)

Are these documents actually intended to be followed and how technical do you want to get exactly? Who's going to follow them? Why would they want to?

Because if the answer is "we'd like to be able (in theory at least) to hand over all network troubleshooting to the marketing department" and you have a complicated network, your documentation is going to include a reprint of an entire CCNA course - and possibly the CCNE as well.

The solution we use is a wiki and a few rules of thumb - such as "if your procedure is more than a page or two long including screenshots or diagrams, it's too complicated to expect someone to reliably follow it. Make it simpler (with scripting and automation if necessary) and document the simple procedure".

There are degrees for this (5, Insightful)

ktappe (747125) | more than 5 years ago | (#26918361)

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]

hire a Technical Writer (4, Insightful)

spyrochaete (707033) | more than 5 years ago | (#26918363)

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.

Re:hire a Technical Writer (1)

gnasher719 (869701) | more than 5 years ago | (#26918889)

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.

You get 90 percent of the value just by using the right attitude. And the right attitude is: If someone is given instructions, and cannot follow the instructions, then the fault is with the instructions, not the person who can't follow it. Assume that the reader of the instructions is a reasonably intelligent person who doesn't have the slightest clue what you are writing about and who is completely incapable of reading your mind. And that they will give you a call at three am in the night and get you out of bed if they can't figure out your instructions.

look around within your own company (0)

Anonymous Coward | more than 5 years ago | (#26918367)

If you don't know where to start, start somewhere! First, decide upon the generic interface. It sounds like you want it to be web based, so that's prolly covered. Next, just find a bunch of Wikis - ask your IT department or Dev department if they're already using one - and start working in them. Read the documentation for each wiki, making note of the features you like, and try those features out. Decide which one fulfills your needs the best, and use it.

As for those idiots who say that documenting what you do is bad for job security: if you're relying on it being difficult to replace you with a pigeon, then you're not bringing too much to the job and maybe this is true. On the other hand, if you bring experience, a good attitude, adaptability, ability to play well with others, domain knowledge, ability to apply that knowledge to reality, etc. then you are hard to replace. Where I work, the ability to communicate what I do is very helpful. I'll leave certain tasks for years, after which I'll have to pick them up again. If I haven't taken good notes, documenting how to perform those tasks, I'd have to relearn them all over again, which would be a net LOSS for the company, making me LESS valuable by wasting resources, and making it MORE likely I'll get fired, not less.

MediaWiki + job swapping (2, Insightful)

mrami (664567) | more than 5 years ago | (#26918371)

Choose any goddamn thing to start documenting (I use MediaWiki, since everybody seems to have some experience with Wikipedia nowadays, so it's not so jarring). Job swapping is essential, since you'll never know how good your doco is until you test it. Choose the best communicator with skillset A, the best communicator with skillset B, and let A do B's job with B watching over, documenting all the way. Swap and repeat. Do the same thing with all other combinations of skillsets you've got. Then test again: when A takes a day off, find a B to replace him/her as a stand-in. See how well he does. If it's not tested, it's useless.

Graphviz (2, Interesting)

Randy Savage (1465063) | more than 5 years ago | (#26918373)

There does seem to be a gap in the market place for a useful dynamic hierarchical graph drawing package. For very complicated procedures I use Graphviz, a freeware by Bell Labs, pretty old now. It takes a bit of hacking but you can create very pretty graphs with high numbers of nodes automatically.

For simple procedures, I just use Powerpoint, and have extra, separate graphs when a particular task can be expanded to a subgraph.

If anybody has any other graph packages to recommend, I would really appreciate upgrading.

Wiki Documentation (1)

D Ninja (825055) | more than 5 years ago | (#26918377)

First off, you mention that there are varying levels of skill sets and that is reason you have to document everything. That will always happen and will not change with any half-decent sized organization, so get used to it now.

As for methods of documentation, my organization has found wikis to be very useful with process documentation. The trick to getting everybody to contribute to the wiki is making it easy to edit. I personally prefer MediaWiki's software, but a lot of people look at the text and freak out. As a result, we employed a "Word-like" document editor and people have really jumped onto the idea. It's still taking convincing of people who are used to huge Word documents that they e-mail around, but the centralized location of the wiki is slowly drawing people over the idea.

One tough sell point of the wiki is, "everybody can edit it! Oh no!" I'd recommend heading this off right away. Force everybody to log in (maybe through their Windows account) so that every change is tracked. Additionally, head this off to explain that this is a huge benefit of everybody being able to edit is that nobody needs to type a huge amount of information. Each person contributes only what he or she knows. (This is all basic wiki information, but when trying to sell a new technology to an organization, you have to really make sure you cover all the areas.)

Re:Wiki Documentation (1)

Lukano (50323) | more than 5 years ago | (#26918403)

This is pretty much my suggestion in a nutshell as well.

A wiki lets you build a knowledge base quickly and easily, that can be ammended and edited by any user. If they screw something up, you can revert the changes and/or isolate who made the error and have them correct it.

Knowledge Management (0, Troll)

Linker3000 (626634) | more than 5 years ago | (#26918433)

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.

It all starts with Policy (1)

techwrench (586424) | more than 5 years ago | (#26918455)

Creating a policy for technical documentation is the best way to streamline procedures.

Once the staff is up to date on the policy, and templates are available, the creating procedures are easy.

It also helps when it comes to revising the procedures.

We used DocBook (1)

resonance (106398) | more than 5 years ago | (#26918479)

We used DocBook to write over 500 pages of process documentation for people to follow. After an initial learning curve with it, it was very easy to code up tagged text. Then it was convenient for it to translate into whatever format we needed, HTML, PDF, etc. That was the easy part. And I agree with other people here - keep it simple.

The hard part is getting anyone to actually read it and use it. Practically nobody did, and less so the further down the skill chain you went. What did work for us was holding regular in-service training sessions with everyone, covering one topic per week, and eventually getting everyone up to speed. We used the documentation as handouts, printing the relevant sections for them.

Dead trees (1)

AKAJack (31058) | more than 5 years ago | (#26918491)

paper and PDF files cannot be "messed" with and passed on with new, incorrect, information added in (without some extra work beyond the problems in that area a wiki presents)

Remember - you are showing people how to use a product and NOT teaching them a new skill or how to do their jobs (hopefully).

It is not unexpected that your company would require some basic knowledge beyond remembering to breath in order to provide security services.

Word (1)

PeeShootr (949875) | more than 5 years ago | (#26918509)

Ummm, we write a document?? We have tons of "Work Instruction" documents that "document" the "Instructions" for how to do "Work"

Underappreciated (1)

chazd1 (805324) | more than 5 years ago | (#26918519)

There are many skills in this area that stay the same through the technology bubble we are witnessing in information technology. When you write you need two things. 1.) Purpose 2.) Target audience.

Concentrating on Audience for this reply... a very good technique is to use a "personna" or "profile." Create a fictious person providing an age, gender, education level, personal habits and so on. You then write that that target. Of course, not everyone who reads will fit in the personna exactly, but your personna will will have a bell curve associated of applicability to other audiences. Agree on the personna with all who are contributing material.

It works almost like magic.

Put it to music (0)

Anonymous Coward | more than 5 years ago | (#26918551)

When documenting operating procedures for nurses to replace doctors, I found it beneficial and easier to remember if you make it sing along:

"The leg's bone's connected to the...knee bone. The knee bone's connected to the..."

Video! (1)

SolarStorm (991940) | more than 5 years ago | (#26918565)

I did a contract for a company with this very issue. They were hiring expensive consultants to come in and fix, undocument procedures and code. Part of the problem was some of the people doing the tasks couldnt write to save their life. So, I got out my cannon video recorder. Did some interviews and video'ed the procedure with screen close ups and questions to the user. Streamed the video to mp4, loaded them on web page, and voila! All procedures demoed and explained by the people who do them. Add some tags to each video and they become searchable.

MediaWiki (1)

cymen (8178) | more than 5 years ago | (#26918573)

We use MediaWiki for that purpose. MediaWiki runs WikiPedia so it isn't going anywhere and it works well. It is designed though for that massive site usage so some things are not so convenient when using it on a smaller scale in a company (and I suspect patches that would change this would not be accepted as obviously whatever WikiPedia uses must scale).

One decision before my time was to use one wiki per group. I would strongly recommend looking into namespaces or some other grouping option that will let you keep everything in one wiki. This will avoid duplication of content, having to explain interwiki linking, maintaining interwiki linking tables, maintaining templates across multiple wikis, and lastly having wiki-wide searching. Using a single wiki may not have been so easy as it is now with current versions of MediaWiki when the decision was made here but now it is certainly straight forward.

Finally, lower your administration overhead by allowing everyone to create, edit and delete. The deletions can easily be reverted so there is no need to go overboard on locking features down.

Sharepoint works.... (2, Interesting)

bev_tech_rob (313485) | more than 5 years ago | (#26918611)

If you are mainly a Microsoft shop, SharePoint works will for posting procedures and related docs. Works pretty good for us. Is a pain to use when trying to rearrange items later, though....

Culture of Knowledge Management (1)

DigitalCrackPipe (626884) | more than 5 years ago | (#26918641)

I am continually frustrated with lack of support for managing knowledge in an organization. If you can get the ball rolling and keep it supported, that's awesome! Here are some criteria I would suggest for your project:
  • Find a way to encourage those who posess the knowledge to document it (even informally)
  • Have someone responsible to assemble, massage, and manage all the documented knowledge
  • Use something that can be migrated - anything that can't be output to text or html might result in lost data when you upgrade to new software
  • Work to develop a culture that uses this knowledge and generates more - it's hard to encourage people to document when management places no value on it (vs. getting work done)

I think the tool is the least difficult part of such an endeavor - changing culture is difficult.

The need is clear... (1)

Gybrwe666 (1007849) | more than 5 years ago | (#26918657)

Documentation is critical to business success, no matter what the business. The reality is not about "protecting" your job or keeping the PHB's from mucking with things. The reality is that it may not be what you do, but what the other guy has in his head that is critical information for your business.

In other words, what happens when a critical employee has a heart attack, or gets hit by a bus. What do you do then? If everyone has their little piece in their head, no one else benefits, and the business overall loses. Or, even more simply, what happens when someone goes on vacation? Or when you go on vacation? Do you (or does the business) suffer because there isn't a way to replicate what that person does?

In this day and age, business processes are perhaps the most valuable thing a business owns. Knowledge can be learned, information can be looked up. But utilizing information in a business is *NOT* as simple as having that information. How information is applied to the business is the key. And documenting that information is the *ONLY* way to get it out of someone's head and into the general domain.

I've had this discussion recently both as part of my business (an IT Services vendor) and as part of my customers businesses. In every case the answer is the same. The processes are the most valuable asset for any company, no matter what the size or business. In fact, the smaller the business, the more valuable, because the likelihood is that in a smaller company there are more concentrations of knowledge, more key people who, if hit by the hypothetical bus, would take with them the day to day processes that run that business.

There are many ways to approach the problem. From embedding processes into a help desk program, to external solutions such as Wiki's, to professional programs that are specifically designed to collect knowledge, flowchart it, and also align it to your business processes.

One of the products that my company handles is specifically designed for this: aligning IT processes to business processes. While this is generally a new concept, and a tough sell, when you can map out what you do in your IT department, and also see the business reasons for why you do it, not to mention see the business impact if you don't do it, the value can be staggering. This is one of the greatest untapped barriers to IT becoming part of the larger business, and demonstrating its value. Far too often IT does things because they need doing, but they don't understand how what they do affects the business, or what value their day-to-day activities actually have in the larger business. And the reverse holds true as well: the business doesn't understand how their needs and requests impact IT, or why they cannot simply "make a wish" and have things their way.

Control of your business processes is the single best way to ensure that IT is doing things the right way for the business, and to clearly demonstrate the value (monetary and otherwise) of their jobs to the PHB's and accountants and other ickey people on the business side.

Documenting processes might be the best way to protect yourself, and save yourself grief. Its only a very narrow and stupid point of view that sees this as being a way to protect themselves, and make themselves "valuable" to the business.

Bill

Translation (0)

Anonymous Coward | more than 5 years ago | (#26918671)

"we deal with a plethora of vendors, versions, and .... skill sets....trying to deal with these varying degrees of technical competency..."

Translation: how can the total idiots where this guy works be equipped to do something productive?

Answer: they can't, they're idiots! They will screw it up, documentation or not. Put them on something harmless and far away from anything important if they must remain on the dole.

There is documentation and then... (1)

timpintsch (842091) | more than 5 years ago | (#26918687)

...There is documentation. One of the most important things in dealing as a large company is to work in making sure everyone can get accurate information everyone needs. One of the most daunting tasks is sorting and maintaining this information as everyone has different levels of proficiency... so, in truth having several different copies of the same documentation geared towards different aspects of the business is very helpful.

How does one explain an OC-192 line from a Marketing perspective? How does one explain QoS routing to Level 1 tech support? How does one explain FCC rules to Sales People and still make that information understandable by customers who have a rough time programming their VCR? These are issues faced in putting together a documentation project for a corporation. Less is never more for documentation and targeted, simplified versions of highly detailed technical procedures are also valuable...

The trick is putting together a system that does all of this and is easy to update everything that needs updating.

document management (1)

nusuth (520833) | more than 5 years ago | (#26918699)

I can't give you any advice on how to document your procedures for your company. However, I have some experience in managing documents. Dead tree doesn't work. Very soon (and especially in the beginning of documentation process) you will run into problems with keeping everyone on the same version of documents. I looked into various open source CMSs based on wikis and other engines and decided to deploy alfresco in the end. Alfresco does everything my company needs: it can keep different revisions and translations of documents with ease, has a simple but functional access control system and an easy way to start workflows and discussions on documents. It also has interfaces for web publishing, network drives, wikis etc. The free version is a bit hard to deploy right but once deployed it is trouble free.

Set procedure vs. record of actions? (1)

meridoc (134765) | more than 5 years ago | (#26918791)

I think you first need to figure out whether what you want is for everyone to follow a certain procedure (bio labs have set protocols) or just to have a record of what work people have done (like lab notebooks). Here are some brief (and incomplete) thoughts:

Protocols, pro:
- high consistency, as long as people actually follow them
- can be easily edited and everyone will be able to follow the improvements
Protocols, con:
- little flexibility, depending on how they're written

Lab notebooks, pro:
- allows flexibility for all situations, allows for worker's ingenuity
- accurate record for worker's actions, as long as they write it down
Lab notebooks, con:
- no consistency from person to person
- no structure or prompts for person to follow

Mindmapping software (1)

Terrasque (796014) | more than 5 years ago | (#26918821)

Mind mapping software is brilliant for that kind of stuff.

FreeMind [sourceforge.net] is a good start. Start with the overview nodes, then add sub-nodes for a bit more detail, then you can add sub nodes to them again, until you're into step by step commands to run.

It is free (GPL), runs on most platforms (Java), can export to html, and is really easy to work with. Saved files are in xml format, and there's even flash / java widgets to read and display the files directly in the web browser.

Here [sourceforge.net] is an example java viewer, showcasing some of the functions of freemind (and being documentation for the java applet)

Asked to document how I Program (3, Insightful)

Direwolf20 (773264) | more than 5 years ago | (#26918823)

I started doing a little software development for my company (when I was hired to do help desk), and I was once asked to write a procedure for that. How do you write code. I replied -- Step 1) Go to college for 4 years and get a computer science degree.

Drupal + CCK + Views (1)

ThisIsAnonymous (1146121) | more than 5 years ago | (#26918831)

I'm in the middle of this same process. I'm using Drupal along with the CCK (http://drupal.org/project/cck) and Views (http://drupal.org/project/views) modules to accomplish this. If you aren't aware of what Drupal (or CCK/Views) is, then please take a look at: http://www.drupal.org./ [www.drupal.org]

Basically, Drupal is a CMS application. CCK allows you to create custom content types for Drupal, thus allowing you to further control the structure of the content that is placed inside of Drupal. I'm using CCK to capture: Objectives, task lists, dependencies, team members etc. for each procedure. Views allows you to display the captured data in various ways. It allows me to generate listings of all of the procedures etc. and they are sortable.

You'd be surprised at how simple this is within Drupal. Give it a look...

One word: WIKI (1)

IGnatius T Foobar (4328) | more than 5 years ago | (#26918833)

It's that simple. Get an internal Wiki up and running immediately, and encourage your team to dump every single little bit of knowledge into it. It won't become a complete repository overnight; it takes time, but as more information flows into it, it will become more and more useful.

Also be sure that your wiki has a full text index so it's easily searchable. This is actually more important than building pages that house tables of contents.

Wiki (1)

rjolley (1118681) | more than 5 years ago | (#26918841)

When users don't know what a term means they can find out and create a link in the wiki to the explanation page. It works where I work (when people remember to use it)

There's no Magic Bullet. Just get things written. (2, Insightful)

cbreaker (561297) | more than 5 years ago | (#26918845)

It really doesn't matter what you decide to use. Wiki, Sharepoint, a file share with a bunch of Word docs. It doesn't matter. Just get things written down.

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.

MediaWiki + graphviz extension (1)

Software (179033) | more than 5 years ago | (#26918849)

MediaWiki for all the text-only stuff. Use the Graphviz extension for nice flowcharts (not necessarily pretty flowcharts - use Visio for that).

Document methods, not step-by-step actions (1)

Gonoff (88518) | more than 5 years ago | (#26918873)

Flowcharts of method but scripts are really bad.

A great example of this the "help" line for an oversized ISP. You get asked a load of irellevant questions because that is what the script says - even though you told the operative precisely what the problem is. They have to follow the over-documented step by step procedure.

Example
Customer Hello? I need a new HDD. I got errors X, Y and Z so I ran your boot CD and it did a BIOS test and said error 7 so please send one.
Helpdesk Please check the following... (for 5 minutes)
Helpdesk Right, so the drive is there and we have errors X, Y and Z. Have you tried reinstalling Windows?
Customer No, the error indicates a hardware failure(5 more minutes>
Helpdesk Do you have our system CD? Please put it in the drive...(10 minutes to run test)
Helpdesk I see you have error 7. This means you will need a new HDD

It is not the fault of the helpdesk that they ignored everything you told them at the start. They are required to. We all know that end users have varying abilities and intelligence. That is where Staff training can save a lot of company time and improve customer perceptions.

Tiddlywiki (1)

dragonb (615590) | more than 5 years ago | (#26918877)

tiddlywiki might be a nice possibility. I like the way it expands sections. easy to lock down. easy portability that anyone can read (only web browser with javascript needed.)

A useful format for documenting practices (1)

__roo (86767) | more than 5 years ago | (#26918907)

When Jenny Greene and I were working on Applied Software Project Management [stellman-greene.com] , we put a lot of effort into coming up with a way to document the practices that we wrote about. We wanted to make them really easy to understand, because we didn't people to have to learn to read something heavyweight or cumbersome.

We ended up using "scripts" (think scripts that an actor uses, not scripts that a shell script uses) that just explain each process or practice step by step. We got a lot of mileage out of adapting the format that we used for use cases -- you can see an example here [stellman-greene.com] -- it's a pretty standard way of writing down use cases, but we'd never seen it used for practices. But it actually ended up making a lot of sense.

That format worked really well for us: we used it for estimation (using Wideband Delphi) [stellman-greene.com] , inspections and code reviews [stellman-greene.com] , developing specs [stellman-greene.com] , planning for risks [stellman-greene.com] , and a bunch of other practices. You might get some mileage out of it too.

Make two different docs... (1)

sirwired (27582) | more than 5 years ago | (#26918921)

I've done this before... what you really need are two separate documents. (Yes, they are a pain to maintain.)

First, you need a "training" document. This is the one with pretty screenshots and terminal logs going over the procedure in excruciating detail, and this document is used to train new folk on your setup. This is mostly utilized as a guide for...

The second one, which is more of a shorthand checklist template. (Few experienced admins will wade through some lengthy "admin for dummies" procedure after he/she has done it a few times.) This document has the information for the change ticket buried inside the checklist, which increases the probability the checklist will actually be used.

Here's a trivial checklist sample of changing directory permissions:

Wrong
User: John
Dir to be added: /foo/bar
Server Hostname: FooServ
Permissions to be set: 345
Charge Code: 3456
Change Request Number: 12345

1) Login to server under admin acct.
2) Set appropriate dir permissions.
3) Update accounting database with charging info.
4) Update chg control db with new permissions info.
5) File TPS report of completed change to PHB.

Sign Here:____________

With a checklist like that, the boring crap after the change is done oftentimes gets skipped because the admin just makes the changes to the server, gets distracted while doing housekeeping, and just signs off the ticket.

Right:
Initials:
____ 1) Login to Server __FooServ__ under admin acct.
____ 2) Set the permissions in dir __/foo/bar__ to __345__
____ 3) Update the accounting database using charge code __3456__
____ 4) Update the change request number __12345__
____ 5) File TPS report to PHB

Okay, that last one will still get skipped...

Anyway, that 2nd checklist forces the admin to actually make some effort at reading the checklist instead of just using the header info, and possibly skipping steps.

SirWired

this makes windows a PITA (1)

petes_PoV (912422) | more than 5 years ago | (#26918935)

Text based O/s's are easy, just write down the command to run, include the runtime options and list the expected output.

With windows you have to capture a screenshot, point out which button to click on, whether it needs a double-click, right-click or dragging anything. Then you have to go through the whole process again for the next level of window/menu.

No wonder graphics based O?s's (or those with graphical front-ends) are so poorly understood and even more poorly administered - no-one has the time to create these bulky and sparse documents and they have even less time to update them when a new release comes out and changes everything.

Pairing FTW (1)

NonUniqueNickname (1459477) | more than 5 years ago | (#26918979)

Writing is half the battle, maybe less. Keeping the docs current and useful is the real issue.
Every time a new guy goes through a procedure for the first time (or first couple of times), hand him the docs and have an old guy watch over his shoulder. When the new guy hesitates or gets stuck, update the docs. When the old guy says "no no, we do it differently now", update the docs. Some will say you're using two people to do the work of one. But you're actually doing three things: Training, maintaining the docs, and executing the procedure. Four if you count "team-building".
Maybe goes without saying, but whatever format you choose for your docs, it needs to be version-controlled.

Whoever will use the procedure should write it (1)

bugs2squash (1132591) | more than 5 years ago | (#26919015)

Walk the end user's chosen representative (the lead member of your operations team, whoever it is) through the process but have them actually write the document with your guidance and send it back to you for approval / comment. The problem, in my experience, is not so much any lack of documentation but the lack of documentation that gets read and understood.

I use English (1)

DragonTHC (208439) | more than 5 years ago | (#26919041)

And simplistic language at that. The more common language you use, the better. use italics for technical details like paths, code, and commands.

And don't forget the explain your conventions at the beginning of the docs.

Postits (3, Funny)

12357bd (686909) | more than 5 years ago | (#26919053)

Postits Everywhere.

Don't forget to answer the "why"! (1)

foo fighter (151863) | more than 5 years ago | (#26919083)

The biggest problem with procedure documentation is the "why" is often left out.

OK, so I need to 'Look for valid traffic on the monitoring interface'. Why? What is the point?

This really helps when technology changes but the core requirements and especially the tech docs haven't. If you know why you're trying to do something you can find new ways to do it. But if all you ever learn is "Click File, then click print, then click OK" you'll only get what you're trying to avoid.

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?
or Connect with...

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>