Slashdot is powered by your submissions, so send in your scoop


Forgot your password?

Best Practices For Process Documentation? 370

jollyreaper writes "I have a nice new IT job with a non-profit. They are a growing organization and management has realized that they need to bring their way of doing business up to a professional level. Several years back, their IT department was still operated like it was in a home office — fine when you're dealing with three people, not so good when there's over a hundred users. IT got its act together and is now running professionally and efficiently. The rest of the organization is a bit more chaotic and management wants to change that. One of the worst problems is a lack of process documentation. All knowledge is passed down via an oral tradition. Someone gets hit by a bus and that knowledge is lost forevermore. Now I know what I've seen in the past. There's the big-binder-of-crap-no-one-reads method, usually used in conjunction with nobody-updates-this-crap-so-it's-useless-anyway approach. I've been hearing good things about company wikis, and mixed reviews about Sharepoint and its intranet capabilities. And yes, I know that this is all a waste of time if there's no follow-through from management. But assuming that the required support is there, how do you guys do process documentation?"
This discussion has been archived. No new comments can be posted.

Best Practices For Process Documentation?

Comments Filter:
  • Tough project (Score:5, Insightful)

    by ccguy ( 1116865 ) * on Wednesday January 30, 2008 @06:21AM (#22232506) Homepage
    In order to (successfully) document all the processes in your company you are going to need support not only from management but from all the staff as well. This is going to be the most difficult thing to get.

    Forget about wikis and all technical solutions you can think of, for now. First, you need to explain everyone what they get by documenting everything. For most people, explaining what they do, how, etc, means to give away their value. I'm not saying it's true, it's just the way many people think, and this is why they refuse to cooperate as much as possible. Asking someone to document everything sounds like ' we can replace you'. In particular, drop the 'hit by a bus' argument.

    So, your project is probably not to be about documenting everything, but probably about improving those processes as well, making life easier for everyone (and making it clear than that's the final goal), etc.

    Once processes are more or less defined (or redefined) with the participation of staff (meaning that they get to give feedback) you can implement a policy of 'all processes need to follow the documented procedure. Procedure can be changed if needed'. This will in turn help to keep your documentation updated.

    Anyway you are definitely going to need help from a change management specialist, human resources, etc.

    • Re:Tough project (Score:5, Insightful)

      by ultranova ( 717540 ) on Wednesday January 30, 2008 @06:40AM (#22232606)

      For most people, explaining what they do, how, etc, means to give away their value. I'm not saying it's true, it's just the way many people think, and this is why they refuse to cooperate as much as possible.

      Of course it is true. The whole reason to document, as given by the submitter, is to make people more easily replacable. Something that is easy to replace is less valuable than something that is hard to replace.

      It simply isn't in anyone's best interests to cooperate with this kind of project; that's why it's doomed from the start.

      So, your project is probably not to be about documenting everything, but probably about improving those processes as well, making life easier for everyone (and making it clear than that's the final goal), etc.

      Improving the process = making it more efficient = making it require less manpower = layoffs. Again, no incentive to cooperate, and every incentive to sabotage.

      • Re:Tough project (Score:5, Interesting)

        by ccguy ( 1116865 ) * on Wednesday January 30, 2008 @06:50AM (#22232660) Homepage

        Improving the process = making it more efficient = making it require less manpower = layoffs. Again, no incentive to cooperate, and every incentive to sabotage.
        See? That's exactly why an expert is needed to sell this to the staff. You need them to see the equation Improving the process = making it more efficient = people is more productive = we can produce more = we can make more money = we can give better bonuses.

        You aren't going to get people on board by having a techie snooping around.
        • Re:Tough project (Score:5, Insightful)

          by AndGodSed ( 968378 ) on Wednesday January 30, 2008 @07:23AM (#22232840) Homepage Journal
          Well, the old adage goes "If you can't be replaced, you can't be promoted."

          If you can get the employees to take ownership of their jobs and see this as an opportunity to:

          a) Learn a new skill (especially for the non-tech savvy types)
          b) Reduce their work load
          c) Create an opportunity to expand their portfolio to the point they are promoted to run a department and/or administer a person that has been employed to do their old job,

          they should buy into this and support the idea.

          Unfortunately as with most great ideas the actual sale is more problematic than the implementation.

          In fact I'd say the sale is key.
          • Well, the old adage goes "If you can't be replaced, you can't be promoted."

            and then there is the old adage that goes "The grass is always greener on the other side of the fence."

            if you are happy where you are, why would you want to be replaced/promoted?
          • Re:Tough project (Score:4, Insightful)

            by CheeseTroll ( 696413 ) on Wednesday January 30, 2008 @10:03AM (#22233718)
            Can't be promoted, and can't really go on vacation, either.
          • Re:Tough project (Score:4, Insightful)

            by BVis ( 267028 ) on Wednesday January 30, 2008 @10:32AM (#22234006)

            Well, the old adage goes "If you can't be replaced, you can't be promoted."
            And the new adage that replaces that is "If you want a promotion or a raise of any consequence, start working for someone else."

            People don't get promoted anymore. They piddle along in a job that they're either too valuable in to be moved, or they're too incompetent/lazy to be given more responsibility. There's no incentive to work hard in this environment; you can't get a promotion no matter what you do.
          • Re:Tough project (Score:5, Interesting)

            by CrazedWalrus ( 901897 ) on Wednesday January 30, 2008 @11:21AM (#22234436) Journal
            Absolutely agreed.

            I started a job as a IT supervisor about 6 months ago. There was very little useful documentation, and very little in the way of process. Everything was locked up in peoples' heads. The results?

            • Extreme pain when someone goes on vacation
            • Every time a particular issue comes up, that person has to drop what they're doing and go work on it, even if it isn't really their job description anymore.
            • Very little confidence that we're doing the right thing when that person is away.
            • Ludicrous amounts of time spent investigating something that a person could have told us easily.

            We had two very experienced people leave in the space of two weeks, and another follow shortly thereafter. Most of the people on my team are pretty new, and we had a hell of a time trying to make up for the knowledge that walked out the door.

            So what did I do?

            Set up MediaWiki, of course. Initially, upper management was skeptical and slightly against, but I did it in my spare time and populated a couple hundred documents into it myself. It took days of boring, tedious work, copying from disparate sources, grabbing emails with useful information and making them into a coherent document...

            The end result was something that, when I showed to the same upper management, they jumped. They made it standard operating procedure to document our processes, and even expanded the site to serve other departments. Amazing, considering it's only been around 3 to 4 months at this point.

            Look, I know people say that docs "decrease their value", but that statement isn't worth its weight in horse shit. The fact is that, if you are an intelligent, useful person, your value is in *improving* the process or product. If you're stuck doing the same thing over and over like a farking monkey, then you're not really worth much more than a farking monkey. Eventually your "vendor lockin" will become obsolete, and then you won't be worth a thing. A genuinely helpful, useful person can simply go on to the new thing and help make that better too.

        • by base3 ( 539820 ) on Wednesday January 30, 2008 @08:07AM (#22233006)
          An outside expert, i.e. a consultant. That will surely freak out the staff. The good news is that there are a couple of guys named Bob available for a reasonable rate.
          • Re:Tough project (Score:4, Informative)

            by ozmanjusri ( 601766 ) <> on Wednesday January 30, 2008 @09:21AM (#22233408) Journal
            The good news is that there are a couple of guys named Bob available for a reasonable rate.

            I'm a guy named Bob.

            Oddly enough, I'm also a consultant who frequently does process mapping, though my rates aren't all that reasonable any more.

            There's no great trick to process mapping, and rarely any resistance or fear from employees if it's done properly. The key is to approach it hierarchically, make sure you get plenty of overlap in your descriptions of activities or procedures, and keep the document live so changes can be documented and errors corrected.

            I generally try to start with functional groups which contain locations, locations which contain equipment, then equipment which requires activities. The main point, which may not be obvious first, is that context is king. There tends to be a lot of self-similarity about business activities, and without the context, important details will almost certainly get lost.

        • Re: (Score:2, Informative)

          we can give better bonuses to management.

          Here, fixed that for you.

          Sad as it is, this seems the way it actually works. For years workers in Germany have refrained from wage raises (which in real is a decrease in income, taking inflation into account) in order to "strengthen and support the land's economy". At the same time managament wages were raised by several hundert percent.

      • Re:Tough project (Score:4, Insightful)

        by psmears ( 629712 ) on Wednesday January 30, 2008 @06:55AM (#22232698)
        Someone got out of the wrong side of bed today ;-) The flip-side to these views is as follows:

        Something that is easy to replace is less valuable than something that is hard to replace.
        Somone who is impossible to replace is impossible to promote

        Improving the process = making it more efficient = making it require less manpower = layoffs.
        Improving the process = making it more efficient = making it require less manpower = increased capacity = PROFIT!!!
        • Re:Tough project (Score:4, Insightful)

          by CmdrGravy ( 645153 ) on Wednesday January 30, 2008 @07:16AM (#22232802) Homepage
          That is a flip side but in reality the other poster is right, as soon as you see any sort of company policy to capture knowledge and processes like this it's an immediate pre-cursor to them moving their operations somewhere cheaper and making you redundant.

          I've seen this happen 4 times now and no one's gonna catch me out again ! You can still be promoted if no one knows how you do what you do because you'll still be around to handover and train your successor whereas the business is not going to have aas much success asking you to train your cheaper replacement.
          • Re:Tough project (Score:4, Insightful)

            by Anonymous Brave Guy ( 457657 ) on Wednesday January 30, 2008 @09:01AM (#22233272)

            That is a flip side but in reality the other poster is right, as soon as you see any sort of company policy to capture knowledge and processes like this it's an immediate pre-cursor to them moving their operations somewhere cheaper and making you redundant.

            I've seen this happen 4 times now and no one's gonna catch me out again !

            Ah, yes, proof by anecdote. Of all the forms of proof, this is second only to proof by intimidation (a.k.a. proof by stating personal opinion as fact) in its effectiveness. ;-)

            Seriously and honestly, I think you've just had a bad run. I've been involved with a major corporation-wide process change/documentation exercise for nearly two years now. Pretty much everyone wants the changes in question and the training to match, because we're not trying to force things on people, we're trying to come up with a sane implementation of ideas that most of the grunts (which includes me in my main job) already support. Making the changes will improve the quality of what we do and make people's lives easier, and having proper training instead of the typical corporate "on the job training" approach (a.k.a. whispers on the grapevine) will give people the confidence to use the new ideas and not screw-up, which again makes everyone's life easier. There is just no way you could interpret the kind of thing we're doing as a precursor to outsourcing. Software is a knowledge industry, and management who still believes in outsourcing and getting rid of all your people with knowledge and experience is pretty much doomed whatever they do about processes.

          • by SQLGuru ( 980662 )
            It really matters what your business is.....

            If you can sell 20 widgets a day and it takes you 2 days to make 20 widgets, then yes, efficiency = more profit. If you can sell 20 widgets a day, but your inefficient process is still good enough to make 20 widgets a day, then being more efficient will just mean layoffs.

            Seeing as how I've always worked for large companies, I've always said that my job was "getting people fired". I'm an I/T guy. The projects I work on are supposed to save the company money (CBA
          • Re: (Score:2, Insightful)

            by ePhil_One ( 634771 )
            I've seen this happen 4 times now and no one's gonna catch me out again !

            Refusing to cooperate won't change the fact, if your job is being migrated it will be migrated, being uncooperative just means they'll have to reverse engineer what you did and earn you a bad reputation. Cooperate and you might win a supervisory position, a recommendation for a new role, and/or a useful networking contact for your next job search.

            In the meantime, it could very well be that you boss is wise enough that he wants more

          • Re: (Score:3, Insightful)

            by jollyreaper ( 513215 )
            OP here. Hi!

            That is a flip side but in reality the other poster is right, as soon as you see any sort of company policy to capture knowledge and processes like this it's an immediate pre-cursor to them moving their operations somewhere cheaper and making you redundant.

            That's not been the case through all the layoffs I've been in. That would require a level of organization higher than I give management credit for. Typical layoffs are stupid, chaotic, and nobody even realizes that key people are no longer doing their jobs, fees don't get paid, and late penalties pile up to greater than the salary cost that was saved.

            What we're looking at here isn't about layoffs, it's about improving training and efficiency. In certain parts of the company, it's like someone u

          • by kent_eh ( 543303 )
            Around here, it went something like this:

            1) Management acknowleges teat we have some pretty broken processes that get in the way of us doing things properly, and generally piss people off. (All workers know that their workplace does stuff that makes their job harder/more frustrating than it needs to be)

            2) collect input about what processes are the most broken (no shortage of finger pointing here)

            3) in depth analysis of the most broken processes (step by step, department by department. This is a long and pap
        • Re:Tough project (Score:4, Interesting)

          by ultranova ( 717540 ) on Wednesday January 30, 2008 @08:45AM (#22233180)

          Someone got out of the wrong side of bed today ;-)

          No, I'm merely trying to do as the marketing class always told us, and view this from the buyers point of view. It's not looking so good :(.

          Something that is easy to replace is less valuable than something that is hard to replace.

          Somone who is impossible to replace is impossible to promote

          Perhaps. But this is only an impediment for the ambitious and confident, and even they can achieve promotions by changing jobs. Besides, we are heading towards a recession, so job security will propably count a lot more than advancement. Let's not forget that security is amongst the most basic needs.

          On top of that, since this kind of move could be a precursor for layoffs or outsourcing, it is likely to spread Fear, Uncertainty and Doubt - and as we all know, people confronted by those tend to react by getting defensive and covering their back ("no one ever got fired for buying Microsoft").

          Improving the process = making it more efficient = making it require less manpower = layoffs.

          Improving the process = making it more efficient = making it require less manpower = increased capacity = PROFIT!!!

          Good for the owners, but frankly, why should the employee care ? He's not going to benefit from it. And don't forget that laying off people to temporarily hike up the stock price is a standard trick nowadays; of course it is a stupid move in the long run, but by then the CEO has already gotten his bonuses.

          In a way I can't help but think that business gets what it deserves. After all the outsourcing, layoffs to pump up the stock price, and abuses of at-will employment by control freaks, there is no trust left between the employees and employers. That means that whatever one does, the other will interpret in the worst possible way. This, in turn, makes it impossible to change anything, because any change is taken as some kind of devious plot, and sabotaged as such. In the long term, it would be much more profitable for everyone to build up sufficient trust that everyone works together rather than against one another; but that would benefit the future CEO and employees, rather than the ones making the decisions right now, who can benefit more if they screw the future for the sake of short-term profits, so it isn't bloody likely to happen. Which, in turn, really underlines why morality beyond mere rational self-interest is neccessary to have a prosperous society...

          • Re:Tough project (Score:4, Informative)

            by grimmfarmer ( 529600 ) on Wednesday January 30, 2008 @09:12AM (#22233348)
            However realistic your observations might be in light of modern corporate "greed culture" (which is different how, from 19th-century "greed culture"?), your pessimistic attitude and lack of treatment of a core criterion betrays the fact that you've never worked for a non-profit.

            I own an IT consultancy that has worked for somewhere between 40 and 60 NPOs in the last several years, among other clients. Call it our "social mission". In contrast to the fundamental jadedness of your diatribe*, people working (not volunteering: working) for NPOs are typically 1) invested in the mission, 2) invested in the mission, and 3) invested in the mission. There's not too much ego going on, least not below the Executive Director level. These people are, by and large, dedicated to the organization and, I suspect, would be more than willing to participate in a documentation initiative. Of the few NPOs we've kept on as clients -- WE have to make a profit, even if they don't -- most don't seem to experience resistance to process documentation. And it's especially crucial in the case of an NPO, where they can't necessarily afford to send more than one person to project management training, or pay for more than one "basic bookkeeping" course at the local community college. We've traditionally worked mostly with domestic violence/sexual abuse organizations, and the brave souls who work at them burn out like crazy. You wouldn't believe the turnover. Whatever knowledge or competencies the organization acquires over time must survive the coming and going of staff, and luckily, the staff generally knows this.

            I guess it comes down to this, really:

            1) process documentation is a necessity of business continuity (I'd be remiss as a consultant if it weren't included in my operational continuity plans for clients);

            2) don't put the original poster off what it a worthy and crucial cause (especially since s/he works in IT at an NPO -- there will be enough challenges coming up, thank you very much);

            3) start your own damned business, if you don't like how you've been treated by your employers.

            * Dude: I've been laid-off, too, by the Big National ISP That Ate the Little Hometown ISP Where I Worked(tm), so I know what it's like to write "thanatopsis documentation".
      • I consider myself on the Socialist side, but you aren't going to help anyone in the mid/long term by keeping people nice and quiet in their inefficient, obsolete jobs just to artificially keep them busy.

        People must acknowledge they have to learn and evolve. Most complaint about career stagnation but the fact is that they don't want to learn ways out of it.

        If everyone thought like you we'd still be living in caves.

      • Re:Tough project (Score:5, Insightful)

        by bscott ( 460706 ) on Wednesday January 30, 2008 @08:39AM (#22233148)
        > It simply isn't in anyone's best interests to cooperate with this kind of project; that's why it's doomed from the start.

        It's not necessarily as simple as that - could be it's just not COOL to document, duuude!

        The group where I work (a small IT services company) is mostly younger guys who like a 'hectic' atmosphere, lots of fast action and explosions, or at least busy troubleshooting schedules. Getting them to sit down and record their time spent on various projects is enough of a hurdle; getting anyone to document "office processes" is more like asking for volunteers to make a handwritten backup of each bit on a hard drive.

        No one's job is threatened - it's a growing company - and everyone's smart enough to realize that things really would work better if we all were on the same page more often. It's just not fun. Even when I point out it's easier than their actual work, while being just as appreciated by the boss - it's not gonna happen.

        Never mind the fact that sometimes "documenting processes" is more a matter of creating them from scratch than describing what's currently done... in a nutshell, if it was easy it wouldn't be an issue worth discussing.

        (I never thought of using a "wiki" before, so I'm already a step ahead just from reading the synopsis of this story!)
      • by samkass ( 174571 )
        The whole reason to document, as given by the submitter, is to make people more easily replacable. Something that is easy to replace is less valuable than something that is hard to replace

        To a point. Presumably the people doing the jobs are good at what they do, and a replacement would be worse. If the only value you bring to the company is your knowledge, you're already of questionable value. Just install wikipedia where you used to sit and let people query it as your replacement.

    • Re:Tough project (Score:5, Insightful)

      by dltaylor ( 7510 ) on Wednesday January 30, 2008 @06:52AM (#22232680)
      Dead wrong.

      1) almost no one knows what knowledge others in their organization lack

      2) very few people really know how much they know

      3) almost no one ever has the time to catalog their knowledge and write it all down (if they do, they probably aren't doing anything and don't know anything)

      Pick something, for example, a set of personal wikis. Start a "test run". Every time someone is asked how to do something by someone else, they don't explain verbally, they put it in their wiki. Between the requester's follow-up questions (also through the wiki) and the answers, there will be the "oral history" captured electronically.

      Management has to provide the resources, and the startup training time, as well as some sort of recognition for those who answered "in form" and for the requesters that followed through "in form".

      One other thought is that "how I do X" could be captured through voice recognition. As a staff member performs a task, they could verbalize the steps to some easy-to-use voice recorder, then those recordings parsed to on-line documents. Allow the staff member first crack at editing as a courtesy (you don't know what was captured), and while they're doing it, they may also think of more input.

      Don't be a grammar Nazi on the wikis (or whatever tool). Save that for the professional training manual writer(s) that end up compiling the "official" procedure manual from the raw data.
      • Re: (Score:3, Insightful)

        by ccguy ( 1116865 ) *

        Pick something, for example, a set of personal wikis. Start a "test run". Every time someone is asked how to do something by someone else, they don't explain verbally, they put it in their wiki. Between the requester's follow-up questions (also through the wiki) and the answers, there will be the "oral history" captured electronically.

        You are missing my point. People is not going to do anything that in the long run they seem to be bad for them (or their employment). You can start all the wikis you want,

        • Pick something, for example, a set of personal wikis. Start a "test run". Every time someone is asked how to do something by someone else, they don't explain verbally, they put it in their wiki. Between the requester's follow-up questions (also through the wiki) and the answers, there will be the "oral history" captured electronically.

          You are missing my point. People is not going to do anything that in the long run they seem to be bad for them (or their employment). You can start all the wikis you want, but it's not going to help if people don't willingly use them, which is not going to happen.

          Dead wrong. Certainly, wikis imposed by insensitive management in an organisation with poor morale are not going to be used. Our company wiki, however, is heavily used. Every single employee contributes information to it, and it is kept up to date and useful without any management intervention. People willingly do things which make their job easier, and for most organisation a company procedures manual is exactly that sort of thing.

        • So tell them either you put it on the wiki or you get fired.

          Doesn't that insentivise the staff a little more if they really are so worried about their job (presumable because they have few skills to offer their employee other than this sacred knowledge)

          In reality you will get some cooperation (I'm currently pushing things like this through at work) and those that don't go along with it need to be dealt with once everyone else is up to speed. (they also look like idiots when everyone else is doing it and the
        • I disagree with the basic premise that people are always logical about their long-term goals. People's actions tend to be dominated by short term rewards, and the feeling that they're having long term success is just one of those. So if you take the most-improved person out to lunch every week (or a gift cert, or something) you can get surprising compliance.

          I like company wikis. I think that's a great step, but I think it's maybe step 3. But it's not step 1 (unless you're already past what I said below
    • Re:Tough project (Score:4, Informative)

      by houghi ( 78078 ) on Wednesday January 30, 2008 @07:30AM (#22232870)
      The "Hit by a bus" thing I often see when people are either sick or on a holiday and nobody is able to tell what is going on, which leads to frustrations by people depending on certain input.

      This can go from billing to system maintence to whatever.

      The best solution, I have found, is to have at least three people able to do a certain task. ! person doing the task, one as a backup, who will still do the task once in a while as to be able to be up to date and a third as backup for the backup.

      The main person is give the responsability of 'his' project. Ownership will cause involvement. This will almost always also cause a more streamlined process. As it is 'his project', he will work harder for it, compared to 'the bosses project'.

      The main thing is to do it TOGETHER with the people, not in spite of them.
    • by niceone ( 992278 ) *
      In particular, drop the 'hit by a bus' argument.

      Or at least make sure you park your bus round back, not menacingly near the main entrance.
  • by LiquidCoooled ( 634315 ) on Wednesday January 30, 2008 @06:23AM (#22232508) Homepage Journal

    (1) Avoid being hit by a bus.

    (2) Refer to 1.
  • ISO for non-profits? (Score:3, Interesting)

    by Naturalis Philosopho ( 1160697 ) on Wednesday January 30, 2008 @06:31AM (#22232544)
    Check with ISO to see if they have a program for non-profits. This is the type of project that you can't just pull out of a hat. You need an organization that's done this before for other sites.
    • Re: (Score:3, Insightful)

      by jhol13 ( 1087781 )
      The certification might not make sense, but 99% of the practices do.

      So, even if you are not going for ISO9001, you should see what the requirements for it are. I was lucky enough to be involved in quality assurance during the period the company got ISO9001 certification.

      Yes, I have heard horror stories how ISO9001 has been interpreted to mean "document everything randomly", which it does not. Quite the contrary, the requirements for documenting are quite lax. Not as lax as programmers would like (i.e. nothi
  • At my company, we have a mixed approach.

    A Company Wiki keeps track of often used Documentation, (Contact info, shopping lists, often used procédures), and a SVN Repository for everything else (project info, the weekly agenda (since we need to see older versions).

    That keeps almost everything in check.

  • My experiences (Score:5, Informative)

    by Anonymous Coward on Wednesday January 30, 2008 @06:35AM (#22232568)
    It's really hard to get people to write this kind of stuff. A wiki will work well for some people - developers and IT types particularly - but I've had mixed joy with non-technical types. I don't think it's the technology that's the problem, it's lack of desire to undertake the task and, in some cases, a wish to feel 'indispensable', which this process is trying to reduce. Some people find that very unnerving.

    Where there is no motivation for the group to start documenting, I personally try and lead by example. If I have a process or a system that would benefit, I write a small and clear document (I try and keep it to one side of A4, three at most) and store it on the network. Generally, it never gets looked at, but when somebody needs to know how to do something, it is there and they appreciate it. I also document other people's processes as and when I need to know what they do.

    After a while, and with some encouragement, people start to add their own documents and the whole thing starts to grow.

    It's difficult though. The worst thing is when you see a company that have invested a lot of time and money writing process documentation that is clearly useless. The danger here is having the false sense of security.

    It's also important to remember that the single biggest potential drain on a company is staff turnover, and this will always be the case, even if you have the best process documentation in the world. People are not cogs.

    That's my (limited) experience. Might also be worth noting that I'm not a manager, I'm a developer, so I am working with and influencing my peers rather than my minions.

    P.S. I hate Sharepoint and would not recommend it at all
  • by spazmonkey ( 920425 ) on Wednesday January 30, 2008 @06:39AM (#22232592)
    You could come up with new ways, of course, but why rock the boat. Just go with the tried and true way of handling these things in American corporate culture; Mandate all employees must stay away from buses.

      To accomplish this is quite simple:

      1. Create new management positions and dept. to determine and create new compliance metrics for appropriate bus avoidance.
      2. Create committee to determine and define best practices for avoiding buses.
      3. Hire PR firm to create awareness of above policies and create slick training videos to introduce employees to anti-bus methodology.
      4. Create HR sub-department in charge of enforcement and compliance to metrics with appropriate disciplinary board and/or retraining.

      See. Simple. Problem solved.
  • My approach (Score:5, Funny)

    by Doug Neal ( 195160 ) on Wednesday January 30, 2008 @06:42AM (#22232618)
    My approach to documentation tends to be:

    1. Put on to-do list
    2. Procrastinate
    3. There is no 3

    Don't know if this qualifies as "best practice", though...
  • by Interfacer ( 560564 ) on Wednesday January 30, 2008 @06:44AM (#22232628)
    Everything that we do on the process control network (big Pharma) is documented in Standard Operation Instructions.
    Those cover everything from installing and configuring a server, to user management, backup and recovery procedures, Policy implementations, ...

    The idea is that all procedures have to be validated in order to be allowed to use them, and if you have to deviate, you have to write a deviation report, and possibly ammend the procedure.
    The plus side is that everything on your system is documented, and can be trained by others.
    The downside is that it is a lot of work to make procedures for all normal operations.

    But if there is a major problem and you have to replace a server and bring up the network at midnight, it is comforting to know that it has been done before, and that whatever you have to do is documented.
    • by dodobh ( 65811 )
      If it can be documented to that extent, it can be automated. You just need to use the right tools to deploy systems.
      • Not on our network.
        The process control software cannot be scripted.
        No unapproved device drivers or software is allowed on any of the machines that run that software.
        The software itself may only be installed manually. I thought of using things like windif to make an MSI file for deployment, but a whole lot of stuff in the registry is variable, and depends on lots of things.

        Then there is user management, which has to be done with paper forms and an audit trail.

        Backup is automated, but recovery can be a 24 hou
  • we've had similar issues. I've found that once you have the process documented it's a good idea to get someone other than the author to run through it. We do this by rotating people on and off the various tasks. This means that after a year or so the entire team knows how to do any one job, all the processes are documented and well optimised and if anyone's hit by a bus we can move on. Of course it also means we can sack anyone without cause for concern but if you're good this won' be a worry for you!
  • wikis (Score:3, Interesting)

    by nsupathy ( 515587 ) on Wednesday January 30, 2008 @06:52AM (#22232682)
    You have mentioned wiki in your posting. Wiki definetly works, especially inside a controlled environment like a team/company. There has to be a strong management support and each individual within the company has to realize that it's there for their own good. But many tend to hide the knowledge to keep their jobs safe. The only way is to tie the wiki update to their performance review cycle. Based on my experience, mediawiki is good for static documentation. twiki is a nice collaboration environment, but you will need IT guys with perl knowledge to effectively maintain and explore new features.
    • Re:wikis (Score:4, Interesting)

      by dazlari ( 711032 ) on Wednesday January 30, 2008 @07:59AM (#22232966) Homepage
      I work in the IT department of a largish retail company and we have over the last 6 months undertaken a wiki implementation; at first as an internal trial and then to roll out to the great unwashed. We're using Dokuwiki [] (php based) which is quite easy to install an manage and has a great active on-line community which certainly helps at the outset. Take time to understand the wiki software world fairly well; use the The WikiMatrix [] to help you discover and choose.
      Some tips:
      • Start with only one area of the business and get it done well. News will spread and everyone will want to be on board.
      • Only deal with one individual from each part of the business. This centralises control and keeps some focus. If it's small and that means you then all the better.
      • Certainly do not keep information on the wiki that is likely to go out of date any time soon. Wiki's are best at creating lots of relatively static documents that can be easily corrected and added to. You don't want to be changing minute critical details on the same pages constantly, such as keeping contacts, products, or business transactions. That is crazy! That's what business databases are for and they're far superior for many obvious reasons.
      • Look to similar on-line wikis for structural concepts. Wikipedia, Wikibooks are good starting points. Link to the "empty" documents you want to create later as part of the early structural creation process.
      • Avoid utilising extraordinarily special wiki features too often as they often become cumbersome to maintain and will scare away many novice users at which the page may be aimed.
      • Be sure and test the wiki features out with several browsers!
      • Add the documents that are immediately usable first; don't just add them for the sake of completion. This will save you time and increase the return on time invested.
  • doc control needs (Score:2, Insightful)

    by MrCanard ( 770177 )
    1. A document control specialist who understands what does and does not go into the vault. 2. The vault, software to manage the documents, something like Carmen []. 3. The discipline instilled into all to trust and use the system. 4. Good backups.
  • Hmmm (Score:5, Funny)

    by Hognoxious ( 631665 ) on Wednesday January 30, 2008 @06:56AM (#22232706) Homepage Journal
    I think you work at the same place as me, except we're not a non-profit. Well, not intentionally.
  • First you have to define an aim for this documentation that management as well as staff buy into. The simplest way to explain the need is repeatability and quality improvement: "if we write it down it'll be easy to teach new people if you're ill, and if something is wrong we can correct it" - don't forget to point out that process errors are not seen as human errors (and get management to confirm that).

    Now, your audience is really the staff - management needs metrics more than the processes. I have found
  • by DuncanE ( 35734 ) * on Wednesday January 30, 2008 @06:57AM (#22232714) Homepage
    Like you I have found the big bang, write it all down approach never works. Try this...

    When something "happens" its an "incident". This is logged - drill it in that nothing gets done unless its logged in "the system". The incident in the system describes the problem or event or required change.

    You use incident tracking software for this. Think bugzilla as an example if you are a development team, but it could just as easily track help desk style issues (the internet is down, my password isnt working etc).

    Everything that happens to that incident is logged in the tracking software. Once a solution is found it is recorded in the tracking software and the problem is closed.

    Then when ever a new incident happens new staff can then search through all previous incidents to find solutions. And certain incident solutions can be highlighted as common solutions or knowledge base articles if they were for a major change.

    Also spot checks can be done by you or relevant leaders/management to confirm that the staff that solve problems are recording what they did (much more easy that checking they updated some large process file).

    Over time your incident history and knowledge base will grow to be a reliable resource of your organisations IT knowledge.

    (There is a couple of things that are missed in this process, such as "test in on test system" first and "only implement production changes in quiet times", put these can be written on a massive sign in the office. Then anyone who doesnt do these basic things can be fired for negligence).
  • by emj ( 15659 ) on Wednesday January 30, 2008 @07:02AM (#22232738) Journal
    Sharepoint is a system to control flows of documents, like a web filesystem for Office documents. It's supposed to grow in a planned way, that means you can't grow new structures. And if you want a Wiki you will have to get another one because the one in Sharepoint is not usable, it doesn't help you write good structured documents just to get a web page going fast.

    Now... You aren't looking for tech solutions, but when it comes to that beware, that there is such a thing as adopting too early.
    • by Gopher971 ( 219910 ) on Wednesday January 30, 2008 @12:28PM (#22235174) Journal
      The main weakness with using Sharepoint as a knowledge repository is that the MOSS search functionality is extremely limited. The search used is the MS developed search, not the search that is used on their OS's or on MSN. When creating a knowledge repository or Knowledge base always ensure that you use a platform that allows you to integrate a search engine.

      The message is brought to you by someone who has been struggling (badly) with a Sharepoint based knowledge base for the last 8 months.
  • 1. define your goals! democracy or not - procedures should be centrally managed but influenced by everyone?
    2. define you tools/methodology/language - make it easy to understand and update by everyone!
    3. run it like RFC's go: make a draft and ask for comments - centrally manage what is acceptable and what isn't
    4. make it structured, indexed and easily available for people to see
    5. make each procedure as short and simple as you can
    6. define exceptions...
    7. go step by step - don't try to do everything at once

  • by elronxenu ( 117773 ) on Wednesday January 30, 2008 @07:09AM (#22232764) Homepage

    From "Maverick! The success story behind the world's most unusual workplace" [] by Ricardo Semler ...

    One of my first acts at Semco was to throw out the rules. All companies have procedural bibles. Some look like the Encyclopaedia Britannica. Who needs all those rules? They discourage flexibility and comfort the complacent. At Semco, we stay away from formulas and try to keep our minds open. I knew our rule book was useless when, as a test, I once distributed some additional pages for it. I asked some managers to read the new sections and give me their reaction. Almost everyone said they were just fine. Trouble was, I had stapled the pages together so they couldn't be read without first prying them apart. Funny how no one mentioned that. All that new employees at Semco get today is a 20-page booklet we call The Survival Manual. As you will see in Appendix D, it has lots of cartoons but few words. The basic message: Use your common sense.
    • Re: (Score:2, Funny)

      by omkhar ( 167195 )
      Clearly Mr. Semler hasn't had to face industry/government auditors....

      Q: Show us your standard operating procedure for background checks
      A: Hey look at this cartoon!!!
    • by ivano ( 584883 )
      His sequel, "The Seven Day Weekend", is also good and probably a better read since it talks about how successful his company has now become :) But I'll put in my 2 cents worth. Documentation is important but always undefined by management. You need to sit with your managers and talk about "best practices" and then explain the consequences of it and the extra time needed. You can also look at Agile Programming where the "documentation" is in your test suite. Either case management needs to explain to you wh
  • People talk a lot of smack about office Wikis. It is true that most people aren't going to edit them or keep their "assigned" parts up to date, I've realized that now. However, that doesn't mean that it isn't an invaluable tool for YOU personally. It gives managers the ability to see details what you're doing, and its a wonderful training tool.

    When I came to my current job, there was no process. No specifications, no standards; 600,000 lines of spaghetti pascal code and probably 100-or-so installations
  • I know ITIL may be a bit big of a standards process to map to a small business, but the processes are meant to be implemented "a la carte." That might be one of your better starting points as the ITIL library can be parsed to focus on those processes you need now, and how best to document them for future use. WHERE you put these docs and how is not important. Once you know which pieces make sense for you now you have a framework of operations to consider and flesh out into real company processes and polici
    • by OSXCPA ( 805476 )
      One warning about ITIL implementation (I work for a consultancy who does ITIL work from time to time) - there are a LOT of software packages out there that stick 'ITIL' in the promo language on the box, and some less-than-competent consultants will try to sell you an 'ITIL solution'. They do not exist. ITIL is a process and methodology - don't let your managers get sucked in to the easy, out of the box fix, 'cause it does not exist.

      ITIL as a framework however is pretty kick-ass. Takes a lot of work to do it
    • Another caution with ITIL. In my experience with the framework it does not model the business appropriately from a purely business perspective. It is a heavy framework with appropriate controls that can best be used on IT services. In my experience, from a high level, the best approach to take is the following.
      • Get buy-in from management and obtain all necessary resources (mostly information). Part of this is to develop a plan of how this will look.
      • Document business drivers, in a NFP org this is vital b
  • This is what I've learned from having to capture information before it all ran away. A large road infrastructure firm had just outsourced operations, staff got big payouts and were happy, a few got bonuses to stay on through the transition. The mandate I had was to grab all the information I could before the entire (large) infrastructure team evaporated. I chose a "gather fast, organise later" approach and picked up a few tools fairly quickly. They were (in no particular order):

    (a) Dekki Wiki appliance

  • Get an external consultant in ... because the consultant will be seen as the physical manifestation of the task at hand and will compel people to help to document their processes.

    Added benefits (and the main point of external consultants): you won't get labelled as 'that irritating bugger who asked us all those questions and is really after my job' and you get to carry on with your day job and not get bogged down in a side project.

    I've got personal experience of wikis and Sharepoint and, by the fact of thei
  • by clickety6 ( 141178 ) on Wednesday January 30, 2008 @07:28AM (#22232866)
    I've seen it where every process was documented - including those that were just common sense.

    Did they really need a process to document how to arrange a meeting that had steps like "book a meeting room" and "invite participants to the meeting" plus a diagram showing the meeting with participants as an input.

    I just imagine a guy sitting by himself in a meeting room wondering why he was all alone, checking the process manual and saying "Rats! I forgot step 37a - invite participants! At least I remembered step 62c so now all these cookies and all this coffee are just for me!"

    • I hope they didn't forget to include a step that says: "Arrange sufficient coffee"
    • Re: (Score:3, Interesting)

      Did they really need a process to document how to arrange a meeting that had steps like "book a meeting room" and "invite participants to the meeting" plus a diagram showing the meeting with participants as an input.

      Yes, they did. How one books a meeting room varies from company to company. If it's written down, you don't waste time trying to find the tribal guru of meeting rooms to strengthen your meeting-fu.

    • I've seen it where every process was documented - including those that were just common sense.

      Did they really need a process to document how to arrange a meeting that had steps like "book a meeting room" and "invite participants to the meeting" plus a diagram showing the meeting with participants as an input.

      You're common sense might be uncommon wisdom for another guy. For example, if you're going to move a branch, it's common sense for me to let the folks know to set up phones. Often gets skipped, we'll
    • by rhakka ( 224319 )
      If you change the name from "process document" to "checklist", and suddenly that sounds like a totally normal, proactive thing to do. Write down all the steps you need to do, and check them off as you do them, so you don't forget something obvious or even not-obvious.

      An incomplete checklist is more of a danger than a help.
    • by kenp2002 ( 545495 ) on Wednesday January 30, 2008 @10:24AM (#22233922) Homepage Journal
      you are grossly underestimating the level of stupidity coming out of American schools these days. Yes, you probably need to document steps like "Invite Participants" and "Attend your own meeting." Jebus Rice Federal and State guidelines require a maximum of 8th grade reading level in writing. A max of 8th grade... WTF!?

      I am at the point I have to document for some of these kids processes like, "In the event that you cannot log in, contact the help desk immediately at xxxxxxxx. You computer not working isn't an excuse to surf the web on the other functioning computer 4 feet away all day. And no problems don't just fix themselves overnight much like your laundry magically gets done by mom..."

      Kids seriously don't undesrtand that they could actually WORK on the other computer. The concept is nearly alien to them. If THEIR computer doesn't work they have no comprehension that they could possible use a different computer.

      Sadly either in a doc, wiki, or presentation you'd be suprised what you have to document now. Tons of kids that can tell you the year the Civil War started, but have no clue why it happened. Plenty of kids that can deploy Exchange but have no idea how to configure it to meet the business needs. They know how to do various steps in configuration but have no concept on how to stich all that together to provide a solution. Their like robots now, complete deterministic people in a digital universe. No analog throught anymore...
  • It's a wiki [] for people who want to take control of the job. It's mostly about extreme programming, but much of it can really be applied to any process system.
  • Wiki Culture (Score:3, Interesting)

    by Kristopher Johnson ( 129906 ) on Wednesday January 30, 2008 @07:55AM (#22232952)
    A company wiki can be very effective if people use it. Otherwise, it's just an electronic big-binder-of-crap-no-one-reads and nobody-updates-this-crap-so-it's-useless-anyway.

    What's really needed is to develop a culture of documentation within the company. Ideally, whenever anyone asks a question that's been asked before, the response would be "It's in the wiki somewhere. Try searching for ...." When new hires start, tell them which wiki pages to read, and tell them they are authorized to fix any inaccuracies they find. Try having online discussions in the wiki rather than in e-mail. Summarize important offline discussions in the wiki.

    When it works, it's really cool.
  • The major problem with documentation is for the most part people believe their work is self documenting. When they code they follow their mind set to write the code. So if they made a document or wiki or whatever you will still get something just as cryptic just except for code you have words. I have worked as a consultant for some of the wolds largest companies, small companies, government agencies, state authorities, Not for profit, Fast Growing-Stable hasn't changed in decades companies. And let me
  • by evanyares ( 753066 ) <evan@ y a> on Wednesday January 30, 2008 @08:12AM (#22233026) Homepage
    Want to know how to sort it all out? Get some sticky notes, and a whiteboard. Write down each suggestion on a sticky note, and stick in on the whiteboard. Step back... look at it. Move some notes around. Group them. Get a dry-erase marker, and draw some boxes, circles, and arrows. Throw away the redundant notes. Repeat. Call in a co-worker. Repeat. Call in your boss. Repeat... as necessary. Now, take a picture of the whiteboard. Get a notepad, and summarize what you've found. Oh... and all those software tools and processes you were thinking about for knowledge capture? None of them work as well as a whiteboard and a pad of sticky notes. That's because none of them let you work unconstrained by artificial structure, and none of them let you step back and take in the whole of your work. By the way -- the second best tool for knowledge capture is a cocktail napkin.
    • Using stickies (Score:5, Interesting)

      by BenEnglishAtHome ( 449670 ) * on Wednesday January 30, 2008 @12:06PM (#22234912)
      Using sticky notes to flow processes was a big deal to on one particular project I worked some years ago. The project team was given a conference room with a giant glass wall that divided it from the elevator lobby. Most people who used "the fishbowl" hated that wall; they'd close the drapes and get annoyed anytime anyone peeked in. And people did peek in; that's why it got the nickname.

      I had a completely different attitude. I opened the drapes all the way and proceeded to cover that wall with sticky notes. As we held more and more meetings in there, team members got used to being watched and learned to ignore it. We developed our own code for note position and color that dictated what sort of action or task was defined on the note. Since the systems we were examining were huge and complex, we wound up with hundreds of sticky notes on the wall and, crazily enough, we could all grok it in toto.

      Eventually, some of our bosses started hearing some water cooler talk about those people in the fishbowl. They started dropping by our floor and lingering in the elevator lobby. They saw our animated and intense discussions (they couldn't hear us) and took in the breathtaking complexity of our sticky note art, then left convinced that we were doing a lot of work. Now, mind you we *were* actually doing a lot of work but we could just as well have been planning where to go for lunch. The folks outside the glass had no real idea. But the impression became widespread that we were all a bunch of creative geniuses running our own skunk works.

      After that project wrapped (and incidentally increased revenues by a few billion, yes, *billion* dollars), I think every one of us parlayed that air of mystery we had created into better positions.

      Sticky notes. I love 'em.
  • by Tsu Dho Nimh ( 663417 ) <abacaxi@hot[ ] ['mai' in gap]> on Wednesday January 30, 2008 @08:24AM (#22233076)

    OHHHH!!! ME!!! I KNOW THIS ONE!!!! Been there, done that, have the shurnken heads and tribal tattos to prove it! Also passed ISO9000 on the first try, with only minor criticism of the process docs I wrote.

    These things become like folk medicine or a mystery cult, with multiple strands of "tradition" passed from Master to Student, with people adding their own ideas into them. You will need to reconcile the varying practices among the practicioners, which can lead to bruised egos and outright rebellion. After you have the real process identified and accepted, then you can decide how to deal with it.

    1. Hire a temporary Technical Writer who had done this sort of thing before if you can. They can act like the outside anthropologist.
    2. Let everyone know that they are going to clean up the documentation mess so that they can handle new hires, vacation replacements and temps without having to handhold them and spend days getting them up to speed (the real value of well-written process docs is as a training aid).
    3. Department by department, identify the shamans: the person everyone goes to for training and problem solving.
      You can expect resistance from some shamans: their knowledge may be a source of power and job security to them. One carrot to dangle is the prospect of time freed to do different things instead of being stuck answering questions and training. A stick is the threat of being fired if it is discovered that thye are not handing over all they know - after all, they could be hit by a bus and you would be no worse off than if they are fired and take their tribal knowledge with them.
    4. Have each of the shamans (or the tech writer, or a secretary) write down the process as they understand it - as they are doing whatever that department does, take notes. In a multi-shaman department, you will have several process documents.
    5. If staff are following unofficial crib sheets and hand-written notes to themselves, collect these and make copies of them.
    6. Someone - preferable the technical writer - takes the transcriptions and other documents and reconciles them. Wherever they are in agreement is a non-issue, provided that it works and doesn't violate regulations.
    7. Anywhere two traditions differ must be reconciled. This may mean consulting the operating manual for a piece of equipment (maybe one tradition is using it wrong) and meeting with the shamans to decide which variant makes more sense, is faster, easier or what.
    8. Write the final document and test it. Have someone follow the new process EXACTLY AS WRITTEN and see what happens. The definition of success is that they can follow the document and complete the process with a satisfactory product ... a completed form, a properly filed case, etc.
    9. PUBLISH ... wherever it makes sense.


    • Follow the process from incoming "raw materials" through to the exit of "finished product"
    • While you are cleaning up the process, check the forms and related documents ... they might be simplified, or they might be the cause of part of your problems.
    • The usual heirarchy is: Policies, Processes, Procedures. Write the docs as modules so you can change a procedure (say if you go from paper to computer filing) without rewriting the a 300-page mother-of-all documents. Policies point to processes, processes point to procedures.
      Refer to operating instructions, do not incorporate operating instructions (I saw one process where EVERYTHING was in the process instrucitons, including how to change the toner on a cdretain brand of photocopier!)
    • Re: (Score:2, Insightful)

      I will have to second this. You need a person who is not intimately acquainted with the process to describe it objectively and with enough detail for the ultimate users of the manual - i.e. people who are not intimately acquainted with the process. Also, the end document is more likely to be cohesive and consistent if completed by one person.

      Where my opinion differs is in the carrot-stick part. Explain to the "shamans" that not all they know will be in the document - you can't write the Encyclopaedia Bri
  • My work has a custom Lotus Notes database. In here we can assign keywords to each piece of documentation, do stuff like screenshots, special formatting, etc. to make everything easy to read and follow. In fact, a good portion of the documentation could probably be followed by a person with basic power user knowledge because of the way we documented.

    But to me, there is really 3 keys on how documentation is successful:

    1. How do we force people to use it and update it? Everytime we discover something that is d
  • Don't forget Plone (Score:3, Informative)

    by div_2n ( 525075 ) on Wednesday January 30, 2008 @08:38AM (#22233140)
    We use Plone for our intranet and it rocks. We have instituted a policy that knowledge such as processes go in there. It's FOSS and has lots of add-ons.

    This takes a culture shift that must be implemented with a mandate from upper management. You can start by placing all of your processes/SOPs in the intranet to lead by example.
  • We use MediaWiki [] (same software used for Wikipedia) to document pretty much everything. It has been very helpful being able to update documentation as you go. One issue so far though is the wiki doesn't make it as easy as we would like to find what we are looking for so the organization or your documentation is important.
  • One problem with documentation is the upkeep because things change
    frequently. If the process of updating the dox were simple and easy,
    more people would do it. We use dokuwiki because it is pretty simple
    and easy to use. When I show a junior admin how to do something on
    the terminal, I can past the terminal session into a dokuwiki[0] page
    and it's there for reference next time. I know it's working because
    now when the juniors call me it's because they don't understand something
    in the dox, not where to find t
  • I've done this, and gotten it to work. The key is to get people seeing what their jobs do first, then getting into the details.

    Get some 11x17 or larger paper. Help them draw up simple (informal) process flowcharts of what the heck they do - with each separate process. Note inputs, outputs, work actions, decision steps - that's enough. Then put them on a wall and you examine the processes across the company. It can also help with inter-group communication, where different people call the same thing by t
  • Someone gets hit by a bus and that knowledge is lost forevermore.

    Solution: Stop hitting people with busses.
  • Until you know what the real work process is, you can't publish anything meaningful (See my comment on FIRST). Then you can publish them in a useful way.

    The critical concept is that the process documents must be easy to refer to while the staff are performing the process, which means available at the point they are needed. There is no sense having the perfect document in a departmental wiki if the persons who need the documents don't have a computer on their desk. There is no sense having a 10-lb binder l

  • Several factors to consider:

    1. You're a new hire and not the CEO. Proceed carefully.
    2. The non-profit's management may be perfectly content with what they have now.
    3. Non-profits usually don't have time or money to burn.
    4. Getting many non-IT people to contribute to a wiki or to use Sharepoint to document their stuff may instantly make you the most hated person in the office.

    I used to work for a company that had a rather big department devoted solely to processing the IT docs we authored into an inc

  • by MrNemesis ( 587188 ) on Wednesday January 30, 2008 @09:38AM (#22233528) Homepage Journal
    The world and his wife has already said it, but wiki's are an absolute godsend. My previous company took me and my partner on due to having a terrible IT outsourcer who charged them a fortune and provided shit service (whooda thunk it, eh?) and one of the first things we added was a wiki. When you're rebuilding an architecture from the ground up, you don't have the time or inclination to write huge tomes of docs, but you do have time to scribble notes in a wiki whilst package XYZ is installing or you're waiting for seven gigs of data to copy over a shoffy broadband link.

    We eventually settled on Zope/Plone, and it made future IT maintenance an absolute breeze. Universal search of the object database meant finding a particular scribble was a piece of piss. Fine grained permissions mean we can safely add all of our backend IT stuff (architecture docs, ISP details, support contacts, machine names, the works) so that no-one else can see it. Web based means it's available throughout the company and usable over minimum bandwidth, inclduing GPRS on my blackberry. The ability to add a "comments" box to the end of every type of page object was an utterly superb idea, as was the inbuilt version control for file attachments.

    Compare and contrast to my current company (who bought out the one with Plone); documentation is an absolute fucking nightmare. We're forced to type it in a very particular format in Word in such an arcane template that one wrong move re-numbering the mis-numbered bullet points can make whole sections just vanish (I've exponded more expletives over word than any other program in history - fine for quick letters, anything more complicated and it always seems to crumble to pieces); screenshots in word look absofuckinglutely terrible, and some docs are little more than a catalogue of screenshots from installing and configuring each stage of the app (useless IMHO because they're practically impossible to edit - no-one goes through it when reconfiguring, removing the obsolete screenshots and putting in new ones), unless you happen to live in one of our sub-domains, whose is such that screenshots that take up the whole width of one of my domains' pages do no appear to exist on their computer (that's right, a completely 60 page blank document weighing in at over 15MB, as far as they can tell).

    On top of the dogged insistence that Word be the holy grail of all document formats, each project team has their own documentation area and since there's alot of "architects hand this to ops who hand this to apps testing who hand this to helpdesk who hand this back to ops who then forward changes back to architects who then hand it down to..." going on, there's a veritable starburst of word documents all over the SAN, all pertaining to different sections of the app with about 80% overlap, much of it mutually contradictory, and since all depts use different (and manual, hence arbitrary) version numbering schemes you essentially just have to talk to practically everyone who's worked on that project to figure out WTF is going on. Since the documentation is in such a state, no-one bothers updating it, to the extent that when it's time to reinstall $app on a different server, you find the name of the database has changed and have the task of tracking down the one DBA who knows which box to look at. The few projects that do have "universal" documentation (typically because they're either small or under the helm of someone who laid down strict rules of where the docs should go to begin with) do so at the expense of permissions - they're typically available to normal users if you know the right path to put in to your run: dialogue.

    Have pleaded and pleaded for a saner document management system, Plone was thrown out for the time being for being UNIX (!), at the moment they're trying to integrate the current docs in sharepoint. The words "fuster" and "cluck" spring to mind, although not necessarily spoonerised.

    With a wiki and a remarkably small amount of self-discipline you can avoid the doc
  • Critical Tasks (Score:3, Insightful)

    by stewbacca ( 1033764 ) on Wednesday January 30, 2008 @10:29AM (#22233984)
    Ahh, finally a slashdot discussion that truly applies to my profession! Let's take the guy hit by a bus example. If work stops because the one person who knows how to do that task is gone, then there needs to be documentation. Here is were I can contribute to the conversation. I'm an instructional designer and we operate with the concept of "critical tasks". A critical task is one that is required before a job can be completed. Instructional designers make a critical task list (documentation) then develop training. The resulting training can be reused for all eternity (with updates) and suffices as documentation. This eliminates the piles of useless "read me" binders, because only things that are truly important are developed for training (and thus documented). Well-designed training ensures knowledge transfer, unlike the boring read-me binder.

    If this post has confused you, I apologize in advance. This is a soft skill that is hard to explain in one paragraph on /. (see my sig for further explanation).

  • To start with... (Score:3, Informative)

    by TemporalBeing ( 803363 ) <bm_witness@yah[ ]com ['oo.' in gap]> on Wednesday January 30, 2008 @11:23AM (#22234458) Homepage Journal
    I'd highly recommend staying away from things like SharePoint and LiveLink. I've used both, and in both cases they get high disorganized and information becomes extremely hard to find. I'm on a project now that uses LiveLink and when asking a question, a lot of people will just go "it's in LiveLink" or "go look in LiveLink" - only LiveLink is so chaotic that it'll take you far longer to find it (if you even can find it) than for someone to just give you the real answer to your question. Same goes with SharePoint.

    Additionally, management looks at SharePoint and LiveLink as a form of RCS, but people will typically not using the versioning side - i.e. go to a document, select add version, upload new version - when uploading new versions of a document - they'll just upload a new document, perhaps with a different name that you may or may not recognize as being a new version of some document X. This only adds to the problem of disorganization I mentioned above.

    That's a really touch job to figure out and do. If you need an RCS like system, then I'd suggest looking at using Subversion via webDAV mapped as drives to people systems or something similar - but you'll still have a problem with people not doing versioning right.

    I've also been in the proverbial "someone was hit by a bus" situation (the person left for a vacation and died; not sure what happened, but it wasn't a bus) and had to pick up the pieces. Fortunately it was just software and the code was fully available (after a time), but even so it took us a full cycle to fully understand what was going on and create our own documentation about it (e.g. adding more comments to the code, writing stuff down for consideration for the next version, etc.) so it wasted a lot of money, but we couldn't avoid it.

    Unfortunately for you, you're at a non-profit which means funds to do anything like this are even tighter, and any hit in finances will likely kill your project first unless management is really 200% sold that it will save them money in the long run, in which case they'll prioritize whose functions you have to document so that they can eliminate those positions - which will only lead to less help from any of the employees. (Even more unfortunate for you it's highly likely you'll hit this kind of scenario in the near future given the economy and 2007's 6.3% inflation rate.)

    So take a breather, think things through and I'd highly recommend starting with upper management with the documentation process, and then working your way down - start with at the top, add the key employees, and end with the employees that have high turnover. (They'll likely have good info already and will feel the most vulnerable, so leave them till last.)

    Good luck - you'll need it.

"I have not the slightest confidence in 'spiritual manifestations.'" -- Robert G. Ingersoll