Follow Slashdot blog updates by subscribing to our blog RSS feed


Forgot your password?
Businesses Software IT

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."
This discussion has been archived. No new comments can be posted.

How Do You Document Technical Procedures?

Comments Filter:
  • bad (Score:5, Funny)

    by tritonman ( 998572 ) on Thursday February 19, 2009 @12:44PM (#26918055)
    Documenting technical procedures is bad for job security.
    • Re:bad (Score:5, Insightful)

      by D Ninja ( 825055 ) on Thursday February 19, 2009 @12:50PM (#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.)

      • Sorry, OP is a bad, bad person for not including tags.
      • Re:bad (Score:5, Informative)

        by ChadDa3mon ( 642255 ) on Thursday February 19, 2009 @12:58PM (#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.
        • Hmm...what is this "documentation" word you seem to keep using?

          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 instanc

          • Re: (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

        • Re:bad (Score:4, Insightful)

          by racermd ( 314140 ) on Thursday February 19, 2009 @09:45PM (#26924441)

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

        by JaredOfEuropa ( 526365 ) on Thursday February 19, 2009 @12:58PM (#26918277) Journal

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

          by Clover_Kicker ( 20761 ) <> on Thursday February 19, 2009 @01:04PM (#26918381)

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

          • Re:bad (Score:5, Insightful)

            by dintech ( 998802 ) on Thursday February 19, 2009 @01:25PM (#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 (Score:5, Funny)

              by DrLang21 ( 900992 ) on Thursday February 19, 2009 @01:43PM (#26918969)
              I used to work at a company where this was a standard career advancement strategy.
          • Re: (Score:3, Insightful)

            by von_rick ( 944421 )

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

          by nine-times ( 778537 ) <> on Thursday February 19, 2009 @01:37PM (#26918893) Homepage

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

            by berend botje ( 1401731 ) on Thursday February 19, 2009 @01:57PM (#26919193)
            Even better, after you're done optimizing your own job, start working with your boss on making him obsolete. He gets promoted, you get his old job. Which isn't all that much work anymore.

            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! :-)
        • Re:bad (Score:4, Insightful)

          by Cro Magnon ( 467622 ) on Thursday February 19, 2009 @03:04PM (#26920201) Homepage Journal

          Also, if nobody else can do your job, it can be a PITA scheduling vacations.

      • Re:bad (Score:5, Insightful)

        by Samschnooks ( 1415697 ) on Thursday February 19, 2009 @01:02PM (#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 (Score:4, Insightful)

          by DrLang21 ( 900992 ) on Thursday February 19, 2009 @01:51PM (#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: (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.

      • Comment removed (Score:5, Insightful)

        by account_deleted ( 4530225 ) on Thursday February 19, 2009 @01:10PM (#26918475)
        Comment removed based on user account deletion
        • by billcopc ( 196330 ) <> on Thursday February 19, 2009 @02:54PM (#26920043) Homepage

          I worked very briefly at Dell, doing corporate tech support (hardware), and well not to brag but I was still #1 in the stats ranking a month after I quit until my averages rolled off... anyway I spent much of my off-call time trying to figure out a way to condense my smarts and experience into easy-to-follow instructions for my neighbours, who were often struggling with what I considered very basic problems.

          To put things into perspective, my average call time was 5 minutes. That includes the occasional hour-long clusterfuck, which means the great majority of my calls were under 5 minutes. The top 10 techs had averages in the 15-20 minute range, and most everyone else was 45 minutes and up. Well now what was I doing differently, besides being the guy with the most hands-on PC experience ? I was being lazy, that's what! And I was committed to sharing my lazy ways with the rest of the crew.

          During the exercise. I learned a few things:

          1. It is damned hard to put into words things that are trivial (to you)

          2. Logic, much like common sense, is a rarity these days

          3. Most people fail to factor in the true cost of support time

          So for #1, I had a non-guru friend take instruction, helping me dumb things down and bridge the gaps until we both agreed he had mastered the situation. He would express his frustration at my poor instructions, and ask a zillion questions until I had a grasp of my own internal thought process, of things that I did automagically.

          For #2, I ran through a large number of scenarios and wrote down my own inner thoughts at each decision point. At the end, I trimmed these down to a rather large, multiple-entry flowchart. The neat thing is it covered both specific problems like "my hard drive is dead" and fuzzy symptoms like "my screen is blank". You would start at the edge, identifying the main symptoms and then you followed the paths until they crossed. At the very middle was the final solution "Replace entire system", the catch-all in case no other endpoint was satisfactory.

          For #3, I dug up details on the approximate cost of support time. This included salary, utilities, and amortized equipment cost. Then I made a list of common support resolutions and their total cost (parts, labour, shipping). This allowed me to show how a long call can actually be more costly than replacing the computer in its entirety, especially if the extensive troubleshooting still leads to component replacement.

          So in the end, we had verbose instructions, a troubleshooting cheat-sheet, and a cost guide. It may have enabled incompetent techs to perform tolerably, but more importantly it gave everyone the tools to learn very quickly. After a week or two with these troubleshooting aids, many people had the common issues memorized and had developed strategies of their own.

          That's what I consider a successful transfer of knowledge. Knowledge is much more than just static information, it's also the process to create more information.

      • Re: (Score:3, Insightful)

        by rah1420 ( 234198 )

        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.

        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

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

      by jetsci ( 1470207 ) on Thursday February 19, 2009 @12:54PM (#26918215) Homepage Journal
      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.
      • by jabjoe ( 1042100 )
        Clean, clear code is the best documentation.

        Why write everything twice? The text version always falls out of date anyway. [] is the best Win32 documentation I know (providing what you are after has been implemented).
        • Re: (Score:2, Insightful)

          by jetsci ( 1470207 )
          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 (Score:5, Insightful)

      by axafg00b ( 398439 ) on Thursday February 19, 2009 @01:26PM (#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 (Score:4, Insightful)

        by smooth wombat ( 796938 ) on Thursday February 19, 2009 @02:43PM (#26919859) Journal

        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.

    • Thank you Terry Childs.

  • Text document (Score:5, Informative)

    by tsa ( 15680 ) on Thursday February 19, 2009 @12:51PM (#26918167) Homepage

    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.

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

      by indytx ( 825419 ) on Thursday February 19, 2009 @01:07PM (#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.

    • 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 docu
      • by tsa ( 15680 )

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

      • by tsa ( 15680 )

        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.

  • by Clover_Kicker ( 20761 ) <> on Thursday February 19, 2009 @12:52PM (#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.

    • by JCSoRocks ( 1142053 ) on Thursday February 19, 2009 @12:59PM (#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: (Score:3, Interesting)

        We are using mediawiki for this; it seems to work great, eventually someone catches stuff that has gotten outdated, and it is pretty easy to edit and track changes. The real problem is that search in mediawiki is just dreadful; the index they use is weird, word highlighting is weird, and search is very important for this kind of application of a wiki. So we have some pressure to move to something else. Personally, I'm looking for a wiki with decent search. Wikis are the perfect medium for internal documenta
  • by Red Storm ( 4772 ) on Thursday February 19, 2009 @12:52PM (#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.

    • I agree. Get thee to a wiki [].

    • 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?

  • ...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 [] 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 (Score:2, Informative)

    by SeanGilman ( 1083559 )

    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 f

  • by eth1 ( 94901 ) on Thursday February 19, 2009 @12:55PM (#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: (Score:3, Interesting)

      Put enough detail in the document so that you can hand it to a marketing droid and have them successfully complete the procedure.

      I'm not sure if this is what you mean, but it seems to be similar to a process I've been using for documenting processes for less technical users (usually QA testers, operations people, or business analysts). What I do is write up a quick and dirty document that I feel covers the basics. Then I get together as many people who will need to use the procedure as possible, give them the document and an in-person walk-through of the procedure, answering any questions they have, and then they take notes and som

    • Re: (Score:3, Informative)

      by nine-times ( 778537 )

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

      A wiki can be simple and printable.

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

    • by merreborn ( 853723 ) on Thursday February 19, 2009 @02:10PM (#26919375) Journal

      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.

      Getting your average wiki up and running from scratch should be pretty simple:

      1. You'll need something like a LAMP stack. You've probably got at least one LAMP box left, even if your whole datacenter burnt to the ground. If push comes to shove, you can set up a package like MAMP [] or Apache2Triad [] on a desktop with zero-effort -- we're talking a half dozen mouse clicks through an installer, and you're done.
      2. Many wikis (e.g., PMWiki []) don't even require a database -- they use a file-based datastore. Unpack your gzip'd and tar'd backup of your wiki directory, and you're done
      3. Okay, so maybe you chose a heavier-duty wiki, like MediaWiki. Ungzip your database backup, and dump it into mysql. Now you're really done

      Version control, edit history, and ease of connecting documents make wikis vastly superior to a directory full of Microsoft Word documents.

    • Re: (Score:3, Insightful)

      by SCHecklerX ( 229973 )

      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?

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

    • by OG ( 15008 )

      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.

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

  • by gr3y ( 549124 ) on Thursday February 19, 2009 @12:59PM (#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.

  • 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.
  • 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 proce

  • by ktappe ( 747125 ) on Thursday February 19, 2009 @01:03PM (#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]
    • Whoever modded this troll is an idiot. The parent has a very good point (albeit said elsewhere too). How many coders who document their own stuff know about information design, for instance?

  • by spyrochaete ( 707033 ) on Thursday February 19, 2009 @01:03PM (#26918363) Homepage Journal

    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.

    • 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 o

      • by Todd Knarr ( 15451 ) on Thursday February 19, 2009 @02:06PM (#26919325) Homepage

        You'll never succeed at this. The Army has a test for officers in one of their advanced programs. The officer is given a mission and has to write out a set of orders for that mission. Those orders are then given to a unit to carry out, with one addition: the soldiers are to do their best to fail to carry out the assigned mission without disobeying those orders (technicalities are perfectly fine as long as no order is actually disobeyed). If the soldiers manage to fail to carry out the mission, the officer fails the test.

        I believe this test has a completely unblemished record: no officer has ever managed to pass it.

        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. If you don't think so, remember that even a character-by-character walk-through of logging on assumes that the person knows to turn the computer on first. The instructions on how to turn it on assume that the computer's plugged in or the person knows where the cord and plug are and how to plug them in, and that either the instructions are written for one particular revision of a particular model of computer or the person knows how to find the power switch on an unfamiliar computer. I happen to have personal experience with just how bad it can get. Helpdesk call from one of our midwest truck stops, reporting that their pumps weren't working. It finally got escalated to me as the developer who wrote the pump-control software, since nobody on helpdesk could figure out why the pumps weren't responding. I went through a few basic checks, then told the manager to go out to the pump island, gave him a walk-through of the internal self-test of the pump, and asked him to run the self-test and tell me what codes it reported. His response: "I can't go out there. A tornado came through and tore the islands up, and the main electrical line's laying on the ground out there sparking.". Turns out that, besides the pumps being physically damaged, the power was completely down and the computers were running on UPS batteries. One would think that any reasonable person would've connected a tornado tearing the pumps half off the islands with the pumps suddenly failing to work correctly, but apparently not.

        • Re: (Score:3, Insightful)

          by snspdaarf ( 1314399 )

          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

  • by mrami ( 664567 ) on Thursday February 19, 2009 @01:04PM (#26918371) Homepage
    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 (Score:2, Interesting)

    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 appreci

  • 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

    • by Lukano ( 50323 )

      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.

  • 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

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

  • 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 yo

  • Sharepoint works.... (Score:3, Interesting)

    by bev_tech_rob ( 313485 ) on Thursday February 19, 2009 @01:21PM (#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....
  • 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 yo
  • 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

  • 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 transl
  • 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 flexibil

  • by Direwolf20 ( 773264 ) on Thursday February 19, 2009 @01:33PM (#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.
  • 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.
  • by cbreaker ( 561297 ) on Thursday February 19, 2009 @01:34PM (#26918845) Journal
    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 for all the text-only stuff. Use the Graphviz extension for nice flowcharts (not necessarily pretty flowcharts - use Visio for that).
  • 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.

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

  • When Jenny Greene and I were working on Applied Software Project Management [], 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 f

  • 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 aft

  • 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 c

  • 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.
  • 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 (Score:4, Funny)

    by 12357bd ( 686909 ) on Thursday February 19, 2009 @01:48PM (#26919053)
    Postits Everywhere.
  • 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.

  • The obvious way is Business Process Management (BPM), such as implemented by ProcessMaker [] and Microsoft's Sharepoint.

    I'm really surprised this stuff hasn't caught on more; it's perfect for managing processes in open source teams, like how to file bug reports, or how to install some plugin.

  • by pavon ( 30274 )

    One of my project managers has been using TIBCO Business Studio []. It allows nested/linked flow-charts like you were describing and he apparently likes it much better than Visio. It is a free "lite" version of some of their other software. I've (fortunately) never had to do anything like that myself so I can only give second hand advice.

    From a user perspective, both our lab techs and engineers have no problems using them. I think that nested flow charts work well on screen, but are not necessarily ideal for p

  • I'm sorry, I'm not familiar with that term.
  • ISO Requirements (Score:3, Informative)

    by Bullfish ( 858648 ) on Thursday February 19, 2009 @02:09PM (#26919357)

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

  • Can't be done (Score:4, Interesting)

    by KGBear ( 71109 ) on Thursday February 19, 2009 @04:15PM (#26921163) Homepage

    Not the way you're thinking. Where I work we use a wiki (mediawiki) and it works as well as any system I've seen, probably better than most. Now for the "can't be done" part:

    Tasks like building a server, installing some software, connecting cables, etc., can and should be documented. Troubleshooting however cannot. Troubleshooting takes profound understanding of all the parts surrounding an issue and how they inter-operate; the ability to think long, hard and meaningfully; the ability to devise experiments, execute them, collect and analyze data and arrive at meaningful conclusions based on all that -- the scientific method, in other words. This is the kind of job that humans do better than machines and it is proverbially difficult to even understand, let alone document -- witness the "expert systems" of 20 years ago.

    The big problem is that all non-technically-inclined people, including most people in management positions, think what we do is something mechanical akin to what plumbers do -- no offense to plumbers, who do things I can't do. From a user's point of view, "I can't print my e-mail message" is not much different from "I can't wash my dishes". Locating a clogged pipe and clearing it does require some technical skills and can certainly be documented. The e-mail printing problem however is several orders of magnitude more complex than that and, although it's probably possible to write a flowchart to document any possible thing that could be wrong in this scenario, it would be ludicrously huge, silly really. And that's talking only about day-to-day. If I'm really good at what I do I will design and implement systems so that errors of that sort are minimized. In other words, we're being asked to do the job of civil or hydraulic engineers on a plumber's salary.

    There, of course, is the crux of the matter. Microsoft in particular, but the whole industry actually, are guilty of selling to managers the idea that this job can be done by drones, at all levels. Management is happy because drones don't cost much. Then, of course, drones are all they can get for what they offer.

    What you want is knowledge, knowledge that can be provided by some, but by no means all, not even most, of the people who work for you. And you're tired of seeing those few good ones go away, leaving mostly drones behind. The only advice I can give you is: do document what can be documented. Make it a priority and make everybody responsible and accountable for documentation. But do acknowledge the really knowledgeable people in your team, treat them and pay them just as you would any other kind of expert. I know you're probably not in a position of paying your tech guru at orthodontist levels, but try to treat her at least as well as you do accountants.

Recent investments will yield a slight profit.