I work in the IT biz. At work, we follow a set of processes called ITSM. I won’t go into the boring details, but the short version is that ITSM/ITIL define a common vocabulary that we can use to talk to our customers about IT and more specifically for me, IT Oursourcing (which is what I do). Sounds stupid, but I eventually became a convert after endless training classes. I use ITSM and understand it and in most cases, appreciate it.
However, there is one area where I think ITSM is killing us. In my job, and in many others, documentation is very important. Unfortunately, we make it the hardest thing in the world to create and maintain it. Why? Because we take the concept of Change Management (which is an ITSM concept) to the nth degree. Change Management (CM) is something any programmer will be familiar with. It just means tracking changes in a consistent manner–just like a bug tracking system or a CVS/RCS/SVN/Darcs/blah blah blah.
Ok, let me lay out a documentation submission scenario:
1. Hal wants to document how to clear a printer queue so that Hal doesn’t get called at 3am to do something stupid like clearing a printer queue. And the lower level peeps need the docs because they may not necessarily be as technically competent as we would like.
2. Hal finds the proper document template, which in this case is a Word document template.
3. Hal has to look up in a spreadsheet what the name and location of this document should be–because we got it all structured. I’m gonna make one up and say its “Windows Level 1 Operations \ Print Queue Management”.
4. I write the doc, maybe throw in some screenshots. It’s not long, doesn’t have to be.
5. Then I create a Change Request (CR) in our tracking system. I think I attach the doc, not sure about that part.
6. Then the CR goes to another group.
7. The have to approve it.
8. Then it goes to another group, and they are the ones with actual write permission to our document storage website application thing. I guess it would be published then.
I’m now going to admit that I’m actually ignorant of the exact documentation process because it changed recently, and my job changed recently, and until now I didn’t really have to do the documentation, I’d just tell somebody else to do it. Anyway that’s a part of the issue here.
If the process is so involved that it is not intuitive given the tools we have (and its not), and it takes days to get something published–then the system is broken. I don’t know how many times I have had a question from a level 1 or 2 engineer and thought, “man, if I wrote this down and put it up on AKM, I wouldn’t get this question again”. But inevitably I never get around to doing it because my attention is always needed in more important places.
The solution is obvious to me. Maybe I’ll even bring it up to somebody who will listen politely, agree, then forget what I said. We need to scrap the documentation system and replace it with a wiki. Wikis have built-in revision tracking. And the barrier-to-entry is extremely low. From the time you have the idea to the time you have published it determined only by how long it takes to write. If the data is wrong, its easily fixed, and you know who changed it so you can flog them.
Ok that was boring. Sorry.
I ended up spending way too much time composing a reply in the thread, so much time in fact that I’m not going to repeat it here. But if you have a Pocket PC, you’ll want to read the whole thing.
(update: here’s Psi 
)