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

Thank you!

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

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

Best Practices For Process Documentation?

kdawson posted more than 6 years ago | from the trusting-it-to-the-little-i dept.

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

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

Tough project (5, Insightful)

ccguy (1116865) | more than 6 years ago | (#22232506)

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

Anonymous Coward | more than 6 years ago | (#22232584)

You don't want them to document everything. Documenting everything 'just because' is a sure-fire way to accumulate loads of worthless, outdated cruft that no-one will even bother reading.

Re:Tough project (4, Interesting)

cammoblammo (774120) | more than 6 years ago | (#22233174)

I agree.

I worked for a while in a small factory that manufactured a few different items. Every step of every job was thoroughly documented, and every workstation (i.e. point in the production line) had a poster on the wall explaining in ludicrous detail exactly how to do the job.

The stupid thing was that they were hard to follow. They had been written in consultation with employees, and at the time everyone agreed they were accurate. The problem was that most of the jobs could be picked up much, much quicker if you had someone showing you. Once you picked up a task you didn't need to look at the instructions.

On the other hand, our employer saw value in making sure all the employees could do most of the jobs in the factory. When I left there were no jobs I couldn't do that didn't require a trade qualification. I wasn't the only one.

Here's how it played: for ISO accreditation we were required to document everything we did. Apparently it guaranteed quality. The owner of the business found more value in making sure employees knew what they were doing, and getting them to do it. We could tell if somebody was deviating from the process because our products wouldn't pass the test suite.

The employer wasn't too worried about buses either. I remember one month about half the staff were away sick, on leave or pregnant. The employer put on a few temporary staff, but on the whole we were more than able to cope with just a few hours overtime a week. There was no appreciable decline in our productivity during that month, and I remember him joking that he could fire half of us and still make his money.

I'm glad he was joking. Apart from the money it was the best job I ever had.

Re:Tough project (4, Insightful)

ultranova (717540) | more than 6 years ago | (#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 (4, Interesting)

ccguy (1116865) | more than 6 years ago | (#22232660)

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

AndGodSed (968378) | more than 6 years ago | (#22232840)

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.

Re:Tough project (4, Funny)

base3 (539820) | more than 6 years ago | (#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 (0)

Anonymous Coward | more than 6 years ago | (#22232668)

My dog man, you're actually complaining about making a small business run more efficiently? You have no idea what you're on about mate. More efficient means cost savings, means more job security in the long run, as the business saves money. Its quite simply a form of job insurance. If someone does get hit by a bus, all that knowledge is gone. You need to keep core working knowledge.

Re:Tough project (2, Insightful)

ultranova (717540) | more than 6 years ago | (#22233072)

My dog man, you're actually complaining about making a small business run more efficiently?

I'm not complaining about anything. I'm pointing out that this project is impossible, and explaining why: it requires cooperation from the very people who are going to get screwed by it.

More efficient means cost savings, means more job security in the long run, as the business saves money. Its quite simply a form of job insurance. If someone does get hit by a bus, all that knowledge is gone. You need to keep core working knowledge.

If you are the one hit by the bus, the loss of knowledge won't harm you. Consequently, it is in your best interests that everyone else shares their knowledge but you won't. Of course everyone taking this attitude leads to long-term harm for everyone, but that doesn't change the fact that any single employee has nothing to gain by documenting his own work, and something to lose.

It's simply another example of the tragedy of the commons.

Re:Tough project (3, Insightful)

psmears (629712) | more than 6 years ago | (#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 (3, Insightful)

CmdrGravy (645153) | more than 6 years ago | (#22232802)

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

ultranova (717540) | more than 6 years ago | (#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 (1)

daem0n1x (748565) | more than 6 years ago | (#22232960)

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

bscott (460706) | more than 6 years ago | (#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!)

Re:Tough project (5, Insightful)

dltaylor (7510) | more than 6 years ago | (#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:Tough project (2, Insightful)

ccguy (1116865) | more than 6 years ago | (#22232730)

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.

Also, this idea implies that everything is eventually asked, which is not true. I can be doing my job just fine, getting documents from one stack, processing them somehow, and putting them in another stack - and no one ever asking what is what I do as long as I do it.

Re:Tough project (1)

BbMaj7 (61539) | more than 6 years ago | (#22232772)

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.

In fact it is essential that the processes change over time. Putting in place must-be-followed processes is counter-productive if there is not also a process to vary those processes. You must expect that the processes put in place today will be found deficient in a few weeks or months.

Put another way, one of the most important processes is the "process review" process.

Re:Tough project (1)

wcrighton (1024243) | more than 6 years ago | (#22232824)

hmm. Process documentation is hard. Displaying it and using it, etc, is the easy part. The hardest part, as mentioned, is finding it. The second hardest part is writing it. Most any wiki would help. Simple interface, not wysiwyg, typically. I like to use confluence as my wiki because my users like it.

Re:Tough project (3, Informative)

houghi (78078) | more than 6 years ago | (#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.

Re:Tough project (1)

niceone (992278) | more than 6 years ago | (#22232974)

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.

Operational manual (5, Funny)

LiquidCoooled (634315) | more than 6 years ago | (#22232508)

(1) Avoid being hit by a bus.

(2) Refer to 1.

Re:Operational manual (4, Funny)

phagstrom (451510) | more than 6 years ago | (#22232598)

(3) If all else fails, make sure you get hit by a PCI bus.

Shoot everyone. It is the only way to be sure. (0)

Anonymous Coward | more than 6 years ago | (#22232526)

If you have no co-workers, no one can tell your secrets.

Or, the other option is to shoot your boss. If you have no boss, you have no problem. Actually, just shoot yourself. Then no one has a problem.

Luckily I'm just a computer program, and thus can't be shot. Does anyone want to play a game of Thermo-nuclear war?

Shove it up your ass (-1, Offtopic)

Anonymous Coward | more than 6 years ago | (#22232530)

Cram it up your ass []

There is no such thing as "Best practices" (0)

Anonymous Coward | more than 6 years ago | (#22232540)

First, there is no such thing as "Best practices". Is there any practice better than any other, in any context ? The answer is trivialy : no !

What you need is :
1) Define the problem and the context
2) To solve the problem and only the problem (i.e. don't create imaginary problems)

Just don't forget : do not call the artillery if you have to kill a fly.

Re:There is no such thing as "Best practices" (1)

Hognoxious (631665) | more than 6 years ago | (#22232732)

Is there any practice better than any other, in any context ? The answer is trivialy : no !
I don't know if any are better, but some are certainly a lot worse.

from what I've seen (1)

theheadlessrabbit (1022587) | more than 6 years ago | (#22232542)

From my (limited) experience with small companies, employees all have their own work to do, and getting them to do something extra is just not going to happen. they will see this 'documentation stuff' as being your job, because it most certainly is not theirs (or so they think)

get management on board, make it something that has to get done.

most importantly, make it something that has a strict deadline! work that can be done 'when you get around to it' does not get done.

Without support from management, this just ain't gonna happen.

I would suggest actually running down one worker with a bus each night until the rest shape up and get on it.

Re:from what I've seen (1)

qwertzisnotazerty (956418) | more than 6 years ago | (#22232608)

i would second that ("get the management on board")

one solution, even if a bit costly on the short term, would be to hire a group of people, just like for an audit, that goes from one worker to the other and does the job of documenting all the processes that are involved.
since they are hired by the organization, i.e. by the management, it is also easy to give them beforehand some guidelines you'd like to be followed.
another good thing is that since they are external, they won't assume anything in the processes.

my 2 cents..

good 2 cents (1)

emj (15659) | more than 6 years ago | (#22232774)

External help is one of the better ideas, a friend told me about a company that did this. It ended up costing about 2 years of work time to get it in place, but apparently they have been running fine now updating their processes the last 4 years.

They had the same situation, growing fast, getting very big. When their buying man left taking all his phone numbers and contact names with him, they started the documentation process.

ISO for non-profits? (3, Interesting)

Naturalis Philosopho (1160697) | more than 6 years ago | (#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:ISO for non-profits? (2, Insightful)

jhol13 (1087781) | more than 6 years ago | (#22233078)

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. nothing), but not a burden if you start any kind of documentation for your projects.

sell them on certification? (1)

JBL2 (994604) | more than 6 years ago | (#22232552)

If your IT department is getting their act together, you might be able to sell management on CMMI or similar certification (e.g., ISO). That's an external standard with a demonstrable (or at least quite plausible) ROI. That may be a little process-heavy for your taste, but it's something.

A Mixed approche (1)

Welsh Dwarf (743630) | more than 6 years ago | (#22232556)

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.


Make new ones (0)

Anonymous Coward | more than 6 years ago | (#22232562)

I've always noticed that the current process is rarely quite what it should be anyway so I can get away with writing a new process and just document that. That way I don't have to deal with completely documenting anything old. All I have to do is make sure the stuff that doesn't make sense isn't in there as a fix in case somethings broken somewhere. Then I get to email all users about my shiny new process and I look important. With the asskicking I get daily its always nice to pull my ego out and stroke it back to full health.

My experiences (5, Informative)

Anonymous Coward | more than 6 years ago | (#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

I say go the traditional route. (5, Funny)

spazmonkey (920425) | more than 6 years ago | (#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 (4, Funny)

Doug Neal (195160) | more than 6 years ago | (#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...

Re:My approach (1)

laejoh (648921) | more than 6 years ago | (#22232638)

Don't know if this qualifies as "best practice", though...

Mmh, item 2, perhaps from XP?

Re:My approach (5, Funny)

youthoftoday (975074) | more than 6 years ago | (#22232724)

There is no 3 because it's a non-profit...

Re:My approach (0)

Anonymous Coward | more than 6 years ago | (#22232914)

Not "Best Practice", but certainly "Most Common"

number three (1)

tinkerton (199273) | more than 6 years ago | (#22233074)


actually, it doesn't appear you were joking. Looks more like the most common approach.

You procrastinate second? (1)

Tatarize (682683) | more than 6 years ago | (#22233188)

My poor boy, your priorities are all out of whack.

Build a collection of SOP books (2, Informative)

Interfacer (560564) | more than 6 years ago | (#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.

Re:Build a collection of SOP books (1)

dodobh (65811) | more than 6 years ago | (#22232792)

If it can be documented to that extent, it can be automated. You just need to use the right tools to deploy systems.

Re:Build a collection of SOP books (1)

Interfacer (560564) | more than 6 years ago | (#22232876)

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 hour nightmare, depending on which server we are talking about, with lots of opportunities to hose he entire network with one misstep.

Unfortunately, there is little except making backups (and not even that in all cases) which can be automated.
In other cases, it is a matter of QA and regulatory requirements to do things according to writtne procedures, with a paper trail attached.

hello, accountability anyone ? (1)

nfractal (1039722) | more than 6 years ago | (#22232654)

If you've got to just document the processes and experiences then tough luck dude.
But it can come across as a decent accountability practice by have the staff update wiki's or some sort of periodical reporting system. There's a fine line between reporting your work and actually marginalizing yourself :)

check the documentation (2, Informative)

happytechie (661712) | more than 6 years ago | (#22232658)

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! See if you can get a senior manager to run the jobs of the mail room clerk or something similar for a day!

wikis (3, Interesting)

nsupathy (515587) | more than 6 years ago | (#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 (4, Interesting)

dazlari (711032) | more than 6 years ago | (#22232966)

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

MrCanard (770177) | more than 6 years ago | (#22232696)

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

Hognoxious (631665) | more than 6 years ago | (#22232706)

I think you work at the same place as me, except we're not a non-profit. Well, not intentionally.

Forget about tools - start with aims (1)

cheros (223479) | more than 6 years ago | (#22232710)

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 that flowcharts work best (most people think visually), but don't make it all whizz bang with click through etc. Just compile a document series, and convert the most current versions to PDF and HTML (I'm assuming you have doc version management in place) - make them easy to access (like on an intranet with search abilities). And do not forget to introduce each new one, this will require training time.

That's all I have time for, sorry.

Incident tracking and a Knowledge base (2, Interesting)

DuncanE (35734) | more than 6 years ago | (#22232714)

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

Sharepoint weakness (2, Insightful)

emj (15659) | more than 6 years ago | (#22232738)

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.

Re:Sharepoint weakness (1)

Anonymous Coward | more than 6 years ago | (#22232826)

It's also a tool to ensure endless Microsoft lock-in. Use FOSS instead.

Re:Sharepoint weakness (-1)

Anonymous Coward | more than 6 years ago | (#22232828)

Sorry, this is incorrect. SharePoint is a platform, not just a product, and all kinds of useful things are being built on top of it. Planning is pretty key but the portal is designed to change over time - in fact the whole system is flexible and scales over time according to need. Workflows can be built and hosted in SharePoint to model your precise business procedures. Metadata is built right into SharePoint so you can tag and manage your content as you like. Finally, Microsoft, vendors, and the SharePoint community are constantly releasing new and updated templates for things like wikis - so you can get get much better ones than the ones that shipped "out of the box". Or hey, build your own.

Re:Sharepoint weakness (1)

snsh (968808) | more than 6 years ago | (#22233146)

The Sharepoint wiki is "not usable"? We've been using it the past year for documenting our server setup and changes. The sharepoint wiki site is one of the few tools that Microsoft got right. It's simple, basically letting you edit, scroll, and click on links. It does not distract you with smart tags, office integration, or XML. And by default it does NT authentication, which is transparent in a typical microsoft shop.

The Sharepoint wiki markup does suffer from div-itis, and it doesn't have the feature set of Confluence, but it's great as a starting point. You put your data in, let it grow, show it to management (who tend to like it because it's gives them confidence that documentation is happening), and then later you can decide to keep it, or export the contents to some other platform.

procedures are usless if nobody can find them (2, Insightful)

hvulin (94104) | more than 6 years ago | (#22232760)

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

Something like a wiki should serve you fine if you define stuff in advance...

More documentation may not be the answer. (3, Interesting)

elronxenu (117773) | more than 6 years ago | (#22232764)

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:More documentation may not be the answer. (2, Funny)

omkhar (167195) | more than 6 years ago | (#22232978)

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

Just do it (1)

tqft (619476) | more than 6 years ago | (#22232766)

Do the binder of crap and give it back to the people who did it and say you to do your job from this for a day.

You go get it back next day - marked up with all the bits they missed.

Redo it. Give it back a week later. After 5 or 6 months - it will be a good document.

Do this with all the low level employees first in every dept.

It doesn't matter how you get the first pass - just get it and give it back to them and have them work there job for a day from it, once every so often.

Beware (1)

JBL2 (994604) | more than 6 years ago | (#22232776)

"Agile Methodologies" = OK, maybe (management's answer). "Lightweight processes," ditto, if you can convince them that there is a process.

"Extreme Programming" = skateboarding, and btw your urinalysis appointment is in 10 minutes.

Documenting things : Its all about people. (1)

CarbonMonoxide (1210306) | more than 6 years ago | (#22232790)

Documenting process involves convincing everyone in the organization. Just tell them that by documenting stuff, they will always have something to show their superiors of what their role was , in case some issue comes up. Nobody will be able to say bullshit about what you did because you have put down everything in the big-fat-binder-of-crap-that-nobody-reads. Everything will be documented => accountability and responsibility is assured. Even if its done sometime later , it has its advantages. Convince people that keeping a work log is a GoodThing(TM).

Ready for ERP? (1)

perlith (1133671) | more than 6 years ago | (#22232804)

Is your company ready for an ERP system? ERPs are notoriously risky. Main advantages would be linking IT and business processes together, extensive documentation of said processes, and significant potential for company growth into the future. Main disadvantages would be time, cost, and non-acceptance by users. Might be overkill for what you are looking to do in the short-term. But something to consider long-term.

Wiki, OTRS, and RCS (1)

davek (18465) | more than 6 years ago | (#22232834)

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 with no version information or bug tracking. The code wasn't even under RCS. I can't say that I've solved all these problems 100%, but I'm well on my way. Using my experience as a guide, here's the steps from no standards to some standards:

1. Get all moving targets under revision control, and write up a simple method of version tagging. This includes software, user documentation, database scripts, etc.

2. Start a Wiki and make a short page for each project. Make rough pages outlining things like the release process and version tagging (as mentioned in #1). Include any developer instructions such as build instructions and dependency lists.

3. Use a ticket tracking system for problem resolution, both internally and externanly. I use OTRS [] , and that is pretty functional (and F/OSS). Bugzilla [] is good too but is a little more quick-and-dirty.

Get that done, and you're well on your way. About 20 years later, and you'll get ISO!


ITIL? ISO 20000? (1)

JasonBee (622390) | more than 6 years ago | (#22232844)

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 policies - the hardware, software, business services and how you managed them. It's an open standard and there are lots of certifications available so it'd be a good sell to management if you're needing a whiz-bang name to throw out. It's not out-of-the box however so you may need to take course (wasn't that predicable?) on the art of implementation to learn to work out how best to apply it all to your real-world scenario. I work in a very large IT organization undergoing an IT Governance shift based partly around ITIL standards and partly around custom models. To date the best money has been spent on ITIL related training as it helps disparate units within a fragmented organization to thing in parallel so at the very least the parts come together having similar processes oriented in the same fashion (level 1 support and how to get it vs level 3 desk-side support and how that comes into play). If it all works out for the best, to use a time-worn analogy, we'll all speak the same language in business service terms rather than having unique business cultures with no real way to translate it all when we merge together. As you grow larger you might see fragmentation of methods and skills across parts of your business that no longer talk to each other daily. While a small business won't build the same organization, if anything it will merely have multiple functions assigned to single people rather than single roles for a single person. You have to figure it all out. However don't focus on the physical tools so much - think how the IT services will service the business going forward. You'd be surprised how different the future looks when you focus on the processes rather than the technology you're integrating. jb

Re:ITIL? ISO 20000? (1)

OSXCPA (805476) | more than 6 years ago | (#22232970)

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 properly though, but as parent noted, it can be done in increments to spread the pain and provide some 'quick wins' to show progress.

Re:ITIL? ISO 20000? (1)

slashbob22 (918040) | more than 6 years ago | (#22233150)

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 because you aren't driven by profit.
  • Document the current process situation (people, rules, resources). How do people do work? If you don't understand the current situation how are you going to move forward?
  • Validate the initial findings and receive early buyin from the organization as a whole
  • Develop a "To-be" model of processes (understanding that there are elements from the previous models which must remain constant) and get buy-in
  • Look for automation opportunities and efficiencies
Obviously there is a lot more than that invovled, but grab a notation (BPMN, UML - something that wont intimidate business clients), document everything, and create a plan. Just a couple thoughts.

Toolsets (1)

Nefarious Wheel (628136) | more than 6 years ago | (#22232848)

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, run on the free VMWare platform. A bit clunky in spots, but extremely quick to get running. Looked at Mediawiki appliance, but I didn't have time to dork around with tuning it to accept images. Dekki just worked, was fast enough, and did the job.

(b) MindJet Mind Manager (Lite) 7. Price of a good tech book, and I could download it. Great mind-map documentation tool, use it for architecture work now. I wish more software worked like this package.

(c) Visio, which was part of our consultant's SOE.

(d) Non-confrontational attitude. "Hi I'm here to document all the great work you've done so you won't have to".

(e) BMC software "Remedy" for issue tracking. Think this was really the only high ticket item, but we just costed it into the transition.

I got a fairly nice commendation and will make my bonus this year, so I'm pretty happy with the combination and how it all worked out. I can heartily recommend all of the above, but if you need a real long-term industrial strength wiki and you're not quite as constrained for time, I'd go the full Mediawiki kit. Ymmv.

Get an external consultant in ... (1)

tyroneking (258793) | more than 6 years ago | (#22232850)

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 their very existence they will not be used - because your less-than-enthusiastic colleagues will call it a 'toy' and not use it (they'll call it 'your wiki', or 'your sharepoint' and you'll be stuck with maintaining it and helping them type things into it for all time ... sob...) - and it's your less-than-enthusiastic colleagues that are the ones who don't follow procedures in the first place. Stick with the pure simplicity of a folder with word-processing documents and diagrams in it and print everything out to paper. Add a lightweight SCM tool in their too, like Mercurial, and run it on a batch process every night.

One final thing, make sure that the procedures are added to your bonus / review / disciplinary procedures ... then the buggers will actually have to follow them.

One final, final thing - do NOT take personal ownership of this problem - get your manager to see it was their idea - or you'll be doomed.

Stand alone Wiki? (0)

Anonymous Coward | more than 6 years ago | (#22232854)

Hey bit of a semi related question.

Where I work we get little support from the gods of IT, and we could REALLY use some kind of Wiki for a lot of our work, does there exist any cand of wikiesque package we could stick on a network drive and view via a web browser without the need for SQL servers and the like?

Thanks in advance.

Re:Stand alone Wiki? (1)

Nefarious Wheel (628136) | more than 6 years ago | (#22232894)

Dekki Wiki appliance. You download it, run up the VMWare program that comes with it, and point it to the virtual image. All well documented, and great online help. Omitting the download time, you're up and running in 2 minutes. Dekki is an Apache+Mono+MySQL app running on a Debian instance inside VMWare. Quick and reliable, and you back it up by taking a copy of the VM file. Recommended.

Documetn the useful processes (3, Funny)

clickety6 (141178) | more than 6 years ago | (#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!"

Re:Documetn the useful processes (0)

Anonymous Coward | more than 6 years ago | (#22233038)

He also forgot step 40b; return stapler to the managerial staff.

Re:Documetn the useful processes (1)

LinuxDon (925232) | more than 6 years ago | (#22233098)

I hope they didn't forget to include a step that says: "Arrange sufficient coffee"

Re:Documetn the useful processes (2, Interesting)

Tsu Dho Nimh (663417) | more than 6 years ago | (#22233102)

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.

Re:Documetn the useful processes (0)

Anonymous Coward | more than 6 years ago | (#22233116)

What you should do is to point out which bits of their office processes obviously need an overhaul and develop a software system to help do it for them.

Make sure that you develop your process management system under the GPL -- and in a bit you can sell it for Sun for a couple of billion...

But seriously, a very well designed software system focussing on eliminating process bottlenecks becomes a solution in an of itself, if you can mutate it to respond to changing business needs.

Re:Document the useful processes (1)

Blue23 (197186) | more than 6 years ago | (#22233162)

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 get notification on a Monday of "um, we're in our new branch and we don't have phones. We need it to work. Can you get a phone system set up for us before lunch?" from something six states away.

Common sense may also be to stop people from using their own "common sense". For example, we have a set of standards we have experience with, tools for, etc. Someone in a branch buys a different component, say a print server, because it's $30 cheaper. To him, that's common sense - he's saving money. But when we the support staff gets a call to diagnose a problem, and the cheep box doesn't have functionality we need to diagnose, or even if it does but we lose an hour of productive time for them and us trying to figure out how to use it's advanced functions, that's a loss.


No silver bullet (1)

tortuosity (1229732) | more than 6 years ago | (#22232888)

The answer is that it depends on your workplace culture. - the Portland Pattern Repository (1)

JetScootr (319545) | more than 6 years ago | (#22232922)

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.

Project Documentation (1)

seebach (1229742) | more than 6 years ago | (#22232936)

There is one step in the process which superseeds any method in documenting. The first piece of paper that describes the project, this paper is the key to documenting.

This paper should explain the essentials, like purposes, goals and methods. From then on you simply have to add changes to this paper. Non of your programmers or project managers will end up with the tedious task at the of the project. This is really simple and easy to implement as well.

And make sure its consize, no need for an essay. Think of what would be nice to know in 3 years.

The Bus (0)

Anonymous Coward | more than 6 years ago | (#22232942)

Why is it always a bus? A man always steps in front of a bus. Can't we think of a more amusing way to have the theoretical employee die?

How about a fatal accident involving a surfboard and an electric guitar?

What gets measured gets done (1)

tuxpert (512567) | more than 6 years ago | (#22232948)

period. Add documentation of the process as a requirement to complete anything and include it in the review for any kind of performance mgmt.

You'll also need to make it easier to get the job done - we have Wiki's as well as auto-generated (hence auto-updated) documentation for technical configuration details where ever scripts can do the job - this makes the job of continuous manual update a lot easier.

Wiki Culture (3, Interesting)

Kristopher Johnson (129906) | more than 6 years ago | (#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.

get people to understand why (1)

kicks-ass (977232) | more than 6 years ago | (#22232984)

A lot of the folks who work with me were dropped overnight into projects they had no clue about, and couldnt get any either , because all the relevant info was with the people who were busy, and no one had any time to transfer the info either. Now that we've learnt the stuff, we've encouraged most of the people to share the info so that others will not have the hard time we had. We use drupal btw. More often than not, its about moving relevant stuff off people's inboxes , and into a content management system that can be acessed by all, besides , searching in drupal is way faster than a mailbox search. Of course all the wikis and CMS's would come to nothing if no one believed it. "buy - in" in management speak . you need it at all levels. and it doesnt stop at setting up a wiki, and leaving it at that. The whole thing is , at the risk of sounding cliched, a process, and some incentive for people to do this ( like karma points for adding stuff) is helpful. you need to have people contributing , and recognize and reward the effort , and make people realize the difference it makes to them. If it just makes the job of , say management or IT better, it wont help . You should be able to show that it helps the people who are contributing to it...

The one pager (1)

travis_torabisu (1229736) | more than 6 years ago | (#22232996)

We run a custom software development process, somewhere in between Agile and RUP. To document this we wanted to keep things as simple as possible, and we managed to do it. A single page document which shows a nice high level flow diagram. It has approx 16 steps, and is very easy to view. The above one pager was captured onto our wiki, and a few noted points were added where necessary to describe it. Whats great is its actually followed by us and is used by the other departments within our company. Much better than the sometimes over documented processes that I've dealt with in the past.

Maybe reconsider what you really want (1)

amirulbahr (1216502) | more than 6 years ago | (#22233008)

Rather than trying to document processes, set up an information repository that staff can draw on to do their jobs.

In our organisation we run a wiki [] on the intranet. Initially I thought we would document processes and I tried to kick start things and encouraged others to contribute. Things turned out a bit differently to what I thought we wanted in the beginning. The Wiki is now a general purpose, knowledge and information repository rather than some procedure manual. IMO, it is much more valuable than any procedure manual could be. Combined with good search functionality, if your looking to get something done, that has been done before, chances are there'll be some articles in the wiki about it.

What I'm getting at I guess is get a Wiki up and running and get the ball rolling with some useful information in there, e.g. letter templates, supplier contacts, whatever is relevant to your organisation. Staff will naturally use it if it means they need to remember less or explain things less often to their colleagues.

Teamwork (1)

jellomizer (103300) | more than 6 years ago | (#22233018)

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 tell you if they have documentation it is week at best, more cryptic then the code as worse. The best way is for every project has at least two people working on it (and mix them up for every project) And insure they are working as a Team not a group. Where they are involved with each others coding and make sure if there is a bug they don't go you wrote it you fix it. Also take notes on status meetings and other meetings on changes and future sections record who wanted the change why they wanted the change and if there was some conflict (which will happen in a good team situation) record others reasons and point out the agreed reason and why) . I world organize the document by module so when people are looking at the code and they see something that someone else asked to changed you may have seen that the original developer wanted to do it that way but the person who made the request said it will take to much time. So they decided to do a tradeoff and do it the other way. In that case there may be a chance the code was written in a way with a hook in the code to put their way back in if they felt strongly it needed it already.

Too much good advice. (5, Insightful)

evanyares (753066) | more than 6 years ago | (#22233026)

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.

Documentation is the key (1)

p1ckled (1229756) | more than 6 years ago | (#22233066)

Documentation is essential in IT, even if it is just scraps of notes with "how to do this" type info. I would shy away from sharepoint unless your company has a lot of money and can afford to give people the correct version of office that allows editing with the version of sharepoint you are running. We have admin staff that that can't cope with versions of office greater than 2000. This means they can't edit any of our documents on the sharepoint server we trialled. If other people are interested then start a simple intranet and start adding documents, let people know about it and soon they will start to contibute. Easy to set up with IIS or apache and some simple html pages on a server or even one of your dusty old pcs - no coding required. Plenty of instruction on this online. Personally, my colleagues are terrible at documentation and my manager has no ambition to write anything down so I use google notes and publicly share it with them if they want to find out how I configured that router or what the passwords are for our web site, or what packages I used to compiile xyz, etc. My gain, as I'm seen as being organised as I can search my notes for stuff that they have long forgotton.

FIRST: Capturing the Oral Tradition (5, Informative)

Tsu Dho Nimh (663417) | more than 6 years ago | (#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:FIRST: Capturing the Oral Tradition (2, Insightful)

AiToyonsNostril (1082283) | more than 6 years ago | (#22233204)

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 Britannica. You just need the structure of their knowledge - that cannot replace their decision-making skills, which, after all are mostly why they are "shamans".

How we do it (1)

chrisgeleven (514645) | more than 6 years ago | (#22233114)

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 documentation worthy, one of the first things we say to each other is "Did you document that?" That reinforcement forces everyone to spend at least a few minutes writing down what they encountered. Kind of like peer pressure. It has gotten so expected that management doesn't even have to talk about doing it anymore, since it is done.

2. You must have a good way to search your documentation. That encourages people to use it, which also encourages people to update it since they use it daily. Our Lotus Notes database has a pretty good and quick search, so everyone uses it (when you have 1000+ documents, last thing you want is to manually scroll through them or wait for a 2 minute search).

3. You must make sure the documentation is readable and simple to follow. Screenshots and some basic formatting go a long way to doing this.

Don't forget Plone (2, Informative)

div_2n (525075) | more than 6 years ago | (#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.

What we do (1)

danon (179211) | more than 6 years ago | (#22233158)

We have SharePoint 2003 - in document terms it's mainly document storage (.doc .xls etc), it's a poor CMS, and has poor doc management built in.
It wins because of the high integration with the office system.
MOSS 2007 should improve on many areas that 2003 was lacking - including some Wiki abilities - but I have no exp. with that.
If you're looking for similar office integration with OpenOffice take a look at: [] - I have not tried this in production - but looks promising.

We also have dokuWiki as a separate service: []

Pluses: fast, easy to use and user friendly, permission management through the web(!!), integration to Windows Active directory (with multiple sub domains)
Minuses: ? flat file storage?. This is really a point of view thing. My first aim was DB storage only - but dokuwiki surprised on other ends so we took it. I don't see real performance issues because of file storage, but you lack some features you'd get if you were running a DB...

If you're looking into commercial Wiki - I was also impressed by Confluence - which would probably be my choice if I had to spend money on a Wiki today. []

Hope this helps...

DocBookWiki works pretty well (1)

smaring (229775) | more than 6 years ago | (#22233168)

I've encountered this same situation. Management wants a formal document, and the developers are more motivated to provide documentation in an ad-hoc collaborative fashion.

While it is somewhat painful to setup, DocBookWiki [] gives you the best of both worlds.

URDAD for technology neutral BP design/documentati (1)

FritzSolms (859937) | more than 6 years ago | (#22233176)

We have developed the Use-Case, Responsibility Driven Analysis and Design (URDAD) methodology which BA's use to document business processes in a technology neutral way. The technology-neutral business process is then mapped onto an implementation across IT systems and manual work flow steps, i.e. it is deployed within an implementation architecture infrastructure. Changes in the implementation architecture or technologies do not require redesign of the business processes, but merely updating the implementation mapping for the technology neutral business process.

Furthermore, the business process across levels of granularity is designed by BAs across different specialist domains, all working on the business model for the organization as a whole.

You can download a paper at -> downloads -> research papers -> urdad.pdf. You will have to register with the site, though. Alternatively you are welcome to send me an e-mail, and I will send you an email with the paper.

Here is a link to the officially published paper:
Solms, Fritz (2007), "Technology Neutral Business Process Design using URDAD", Frontiers in Artificial Intelligence and Applications, vol. 161, IOS Press, pp. 52-70, ISBN 978-1-58603-794-9


We put those types of things in a wiki (1)

smelroy (40796) | more than 6 years ago | (#22233186)

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.

we use dokuwiki and vnc2swf (1)

bl8n8r (649187) | more than 6 years ago | (#22233216)

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 the dox. If you have a gui app you need
to demo, hook up vnc2swf[1] and post the flash file as a link in dokuwiki.

[0] - []
[1] - []

Sharepoint/Wiki Experience (0)

Anonymous Coward | more than 6 years ago | (#22233230)

My company has had a Wiki for over a year now, and the only people that use it are those who set it up in the first place (me included). Management recently heard about Sharepoint, so now we're building a Sharepoint server, which I have a feeling will get used about the same amount as the Wiki. I work in an IT services company, and the target audience was the 10-15 engineers that we have... technical people. At every engineers meeting, we always mention the Wiki and how it's only as good as what you put into it, but nevertheless, nobody ever reads it.

I really wish it got used by everyone, because it's been a great tool for me and the one or two other people who use it. Every task I do I always ask myself, "Could I put some documentation about how to do this in the Wiki in case this has to be repeated by someone else?" If other people adopted that mindset, I'm sure there would be a lot more documentation in there.

Oh well, it looks like it's going to be replaced by Sharepoint now anyway...
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?