Slashdot Mirror
Best Practices For Process Documentation?
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?"
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 '...so 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.
(1) Avoid being hit by a bus.
(2) Refer to 1.
liqbase
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?
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.
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.
-I only code in BASIC.-
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.
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.
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.
David
Ask 8 slackers a question, get 10 awnsers (a citation, but I can't remember from who)
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.
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
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 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...
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.
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
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!
--
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.
#include std_disclaimer.h
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 http://manedge.com/index.asp. 3. The discipline instilled into all to trust and use the system. 4. Good backups.
I think you work at the same place as me, except we're not a non-profit. Well, not intentionally.
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
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.
Insert
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 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.
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...
From "Maverick! The success story behind the world's most unusual workplace" by Ricardo Semler ...
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.
The Singularity is closer than you think
Quant
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.
"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 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).
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.
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!
-dave
6th Street Radio @ddombrowsky
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
(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.
Do not mock my vision of impractical footwear
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.
... 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.
... then the buggers will actually have to follow them.
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
One final thing, make sure that the procedures are added to your bonus / review / disciplinary procedures
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.
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.
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!"
----------------------------------- My Other Sig Is Hilarious -----------------------------------
The answer is that it depends on your workplace culture.
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.
Pavlov wouldn't be so famous if he'd used a can opener instead of a bell.
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.
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?
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.
-- Ravi
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.
...." 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.
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 it works, it's really cool.
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...
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.
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.
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.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
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 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.
...Profit!
actually, it doesn't appear you were joking. Looks more like the most common approach.
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.
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.
TIPS:
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!)
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.
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 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: http://www.o3spaces.com/ - I have not tried this in production - but looks promising.
We also have dokuWiki as a separate service:
http://wiki.splitbrain.org/wiki:dokuwiki
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.
http://www.atlassian.com/software/confluence/
Hope this helps...
Dan
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.
Cheers,
=Blue(23)
LITTLE GIRL: But which cookie will you eat FIRST? C. MONSTER: Me think you have misconception of cookie-eating process.
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 http://doc-book.sourceforge.net/homepage/ gives you the best of both worlds.
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 www.solms.co.za -> 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
Fritz
We use MediaWiki http://www.mediawiki.org/wiki/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.
Switching to Linux can be an adventure!
My poor boy, your priorities are all out of whack.
It is no longer uncommon to be uncommon.
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] - http://wiki.splitbrain.org/wiki:dokuwiki
[1] - http://www.unixuser.org/~euske/vnc2swf/
boycott slashdot February 10th - 17th check out: altSlashdot.org
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...
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 two names.
You will probably have to micromanage the process - these people aren't used to thinking that way. "Amy told me that she fills out a form and sends it to you, Bob. What do you do with it?"
Emphasize that you are creating a living document - one anyone can and should change if we find a better way, or some new requirement comes along. Flowcharts are easy to change.
Draw it all up in Visio or something and print it out big, then review it individually (with your input people), then with their group, and finally in inter-group meetings. Walk through each process with everyone (high level). This is the 'get buy-in' phase.
You are trying to drive out inefficiency. If two groups are doing the same thing, or something gets routed around three times when twice would work - that is what you are trying to fix. There is plenty of work to do - you are just trying to get people to do less unnecessary work.
Finally, you can use the flowcharts as the table of contents to the Big Manual No One Reads (where the picky details are stored) - if someone needs to find the part in question, they can (in theory). The details will change and people will need to keep their part updated, this will be an ongoing but smaller problem.
Someone gets hit by a bus and that knowledge is lost forevermore.
Solution: Stop hitting people with busses.
An admitted 'plug', for extended discussions of Process Documentation in many scenarios read through http://elsmar.com/Forums/forumdisplay.php?f=16
Process documentation is very company and scenario specific.
We have a dual approach (by "we" I mean the IT and Business side of a large educational institution).
For document management, we use Sharepoint. This contains both product documentation, project documentation and other types of document generated by management types. If you already have Sharepoint and want to keep everything in one place then it also does Wikis, however they are appallingly bad in that there is no WikiMarkup - you either use the WYSIWYG editor or you type fluent HTML. It's good for non-technical users and may be all you need to fill in the gaps between Sharepoints "big binder full of documents no-one ever reads" approach. Sharepoint iss basically just a web-based file-store that is searchable.
For documenting processes, procedures and textual information we use a Wiki. The one we use is called Confluence from Atlassian Systems, but it costs money (although for non-profits it can be free/cheap). For your organisation something less Enterprisey might be a better cost/benefit calculation... The advantages of a Wiki are that it's a bit more freeform and accessible - good for documenting quick fixes, simple procedures and information you might easily forget.
Users documenting things generally like a Wiki better, because they don't have to load up Word, find the standard template, work out how to lay things out etc. They can concentrate on the information and let something else deal with layout.
Millions of users are clamoring for Leopard 10.5.2, and you shit out 3 obscure bug fixes to iWork '08. Good job guys. Meanwhile, my MacBook Pro wifi still goes up and down like a yo-yo. Ever fucking heard of priorities?
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 locked in the manager's office. Pick a color, preferable a gaudy one, and have a designated location for the "purple binder" with instructions for each step of the process.
The easiest way to handle this for printed documents is with a copy of the document, and sticky notes. As requests for minor changes come in, mark up the page and flag it with a sticky note. When the scheduled review/republish time comes around, or when a major unscheduled change lands on your desk, it's easy to go through the flagged pages, making each correction and marking it off. Then you file that copy, and start again with a fresh copy of the updated manual.
These should cover what happens to the product (which may be a client, or a manufactured product) from the time it reaches that station until it is handed off to the next station.
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 incredibly strict format. I got used to the insanity of it all. I can't tell you the number of times we needed to refer to these documents, likely never.
Then, a few years ago, I switched to a big company that descended from "oral or unorganized documentation" crowd but which had different factions who did things their own way depending on the individual in charge. At first I was pissed at the lax and fractured way I perceived them to be doing things. My career would have ended very quickly if I tried to manhandle everybody into what I thought was a "Is This Good For The Company?" type of philosophy. I learned to adapt.
Oddly enough, there is a new layer of bloat within my company (record profits + 2% raises = more bureaucracy) trying to get the IT crowd on the same page, so-to-speak, about everything. To say they're hated and despised is to put it mildly. What do they say? Those who can't teach, teach gym. Well, the IT equivalent of that go into this sort of job.
Be careful, man. Tread lightly.
As a consultant, I am replaceable by concept and hired for time-limited operations, so I have nothing to lose from teaching others my work.
Thus, when I got to the last new workspace and was "shown the ropes" I carefully wrote it down, including the tacit knowledge I observed that the regulars were blind to, because they lived and breathed it.
I made sure to use brief and simple language, it was a leaflet for own quick referral I was concatenating, not an educational paid-by-word book for others. "When this do that" "Ask NN when this happens" "Z is slow so do Q instead" "First file J then update register K and enter L in database M", and so on.
It was an ongoing project, so I labeled it by revision number which was a good thing, because this text very soon circulated among regulars and given to newcomers. My boss was delighted.
I also write careful logs on my work which has turned out to be invaluable many times, especially when writing reports and I can just cut&paste from the logs.
Many people hate documentation work. It is probably because they do it wrong. Writing docs should be like speaking to people who are really interested in what you have to say about your work.
The Air Force uses "continuity books" for the many additional duties personnel have to perform - everything from maintenance of technical order libraries to tool boxes to organization budgets. The books contain points of contact, technical references, and abbreviated process documentation. These are invaluable because turn-over for most positions happens every couple of years at a minimum.
Continuity books are inspected on a regular basis - usually at least once a year by the organization itself ("self-inspection") or a higher headquarters inspection team. If they weren't inspected on a regular basis they would quickly become "big binders of crap nobody reads." The key to whatever system you decide on is management buy-in and some sort of regular evaluation process to ensure the information remains current and applicable.
What?
We've started using Microsoft OneNote. It's pretty slick because multiple people can access it at once and you can organize by tabs or sub tabs or whatever. It may not be the best but it's working better for us than a bunch of scattered documents thrown into a bunch of folders on a shared drive. This way all of that information is searchable from one location. We like it.
- Avoid management edicts - the staff have to WANT to document the processes, so you must work out what the benefits to the staff are, and point them out (repeatedly)
- Make the staff who operate the process owners of the documentation, with the rights and access to keep it up-to-date
- You MUST find a way to enforce proper process design concepts and discipline or you'll
end up with an inaccurate misleading shambles which no-one uses just because it's not right
- You need to show flows in 2 dimensions, and be able to drill down into any step to see the detail below it (and then drill again and again)
Tools"Cock Up Your Beaver" does not mean what you think. This sig is intended to clog filters and annoy do-gooders
And I quote "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 find it ironic that most companies I have worked for went with this approach. In todays modern society most people will not read it if they cant search threw quickly and find the exact parts that they want to read. You can thank google for this. We have a whole bookshelf of training manuals that have probably not been touched sense they were put there. I just find it quite ironic that there is a wealth of information that nobody uses because it is too difficult to read and keep updated.
I also agree that there are better methods however you have to have company wide acceptance. If you cant get everyone in the organization to agree to use and maintain the data then the data will become outdated and worthless. When this happens it makes IT look bad because it was there idea to put all the data in an easily searchable/updatable format that people could use (but chose not to).
It becomes one of those things that you may never get implemented the way it is supposed to be.
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.
He's right! Failing to have an easy way to submit error corrections and updates, and failure to assign a regularly scheduled task to update the documents is the way most organizations get into the mess. When no one knows how to ask for a change, they scribble the changes in the margins. When processes don't get updated as the work flow changes, people develop their own traditions and the manuals gather dust.
Typically, the first few months will have changes coming rapidly as people discover that what they documented was not the best way to do things. Then it settles down into typo-finding and slow modification for a while. Then some policy changes and there will be another flurry of changes ot implement the new policy.
My recommendation is to let typos and non-confusing errors accumulate until there is a regularly scheduled update time OR a major unscheduled change. Then everything gets swept up in the change and you start fresh.
Printed documents should have a "who to contact for error corrections and changes ot the process" page.
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) because it unnecessarily requires people learning a pretty new way of doing things. To clarify that - I'd go ahead and set it up, and let any dept/team/person that you can get excited about using it of their own volition use it. But it wouldn't be the first thing I recommend to management to really push.
If you mostly have users actually in an office, Step 1 in my opinion is a versioned shared drive. A big place on a shared drive where everyone is supposed to save essentially everything. If it's not big and you have restrictive requirements on what can go in there, this won't work. This should have individual home directories, but should also have top level directories by project and team - it should be clear that putting things there is preferred. You can claim (accurately) that putting stuff there guarantees that if their HD dies they'll be able to really quickly get to the files on someone else's computer. (And obviously you'll be frequently backing up the shared drive, because you're putting a lot of eggs in that basket.)
The biggest technical problem with this theory is overwriting. You need frequent versioned backups to keep overwriting from being a problem, and - less commonly true - you need to be able to recover them very quickly. If this were my problem, I'd use Subversion. That is, I'd setup a Subversion server on a different server & drives (for increased redundancy) and I would automate a process of committing all the shared-drive changes to Subversion, probably several times a day, but at least every night. People who merely use the shared drive never touch Subversion, but people DO have access to the Subversion repository(ies) directly.
This technique means that: a) desktop users don't need to understand syncing at all, just use a remote drive you can setup for them. b) desktop users who WANT to recover earlier versions without asking you can choose to learn how to get old versions from Subversion - so those people who are most likely to be really worried about some other person touching their files can feel MORE in control than they did before. c) laptop users who learn syncing can participate with a local copy of stuff from the Subversion repository, too - which they can update with internet but can ALSO work on remotely.
Looking for freelance Actionscript (Flash/Flex) or ColdFusion work and/or freelance developers. Email me, put Slashdot
I have a nice new IT job with a non-profit.
are we suppose to be impressed? no one cares.
In all my years in IT I've never seen a phrase in common use with less meaning than "best practices." Has anyone seen my big book of best practices? Can't seem to find it anywhere. It seems to be one of those phrases reps use to make themselves seem superior, like they know the answers. Funny how often best practices happen to include the very product they're selling. Amazing. It's all bulls***.
The first thing you have to do is get control of your desktops. If users can install...whatever...you're never going to get control of your internal processes. Users will be installing trialware, freeware and all manner of craptacular little gizmos. The object is to move toward a company portal with a common set of applications for email, contacts, IM, calendaring, corporate wikis, and document storage. Personally, I don't like MSFT solutions for any of those services and that includes Sharepoint. Web mail seems to be a better solution from a portability standpoint. Most companies aren't quite ready to turn everything over to Google Mail...yet, but that may change over time. User acceptance will drive corporate acceptance.
If you can get everyone using the company portal, then you can do some stuff from a documentation standpoint and actually make use of it. Start analyzing how departments work and focus internal development on their business processes. Web-enable their applications and move toward tighter integration with the portal. The more work processes are tied to the portal, the more likely it is to get used. The more web-enabled services you can offer the less critical the underlying operating system. If a company wants to position themselves to have options to the MS upgrade treadmill-o-rama, that's the way to get started down the road.
That's our life, the big wheel of shit. - The Fat Man, Blue Tango Salvage
A wiki has worked wonderfully where I work. The problem with a wiki is typically momentum. Usually it helps if technical staff, who tend to be more comfortable with the technology, lead the charge. We began by documenting our internal processes. Next we started documenting projects that involved other people. Then when we came to meetings with non-technical staff we would explain things then remark "we've also documented this in our wiki". After a while people get used to the idea of documentation being in the wiki. The final step was to start documentation on non-technical processes and let people know it was there, encouraging the stake holders to fill in gaps and "correct mistakes". By approaching the end users as 'experts' and seeking their input the contribution seems more worthwhile to them, and less like documentation.
Putting things in a wiki has enormous advantage over a binder-full-of-stuff. The largest being the ability to quickly search the wiki. The wiki's collaborative editing features also help to make the wiki more evolutionary, reducing the chance that your documentation will be out of date. Not to mention the wiki saves a lot of paper and is available to anyone sitting anywhere at a computer.
The main problem I've seen with the wiki is quality control. Many people in an organization are extremely knowledgeable about their own business process but aren't necessarily the best writers. This can be problematic, especially if authors come to feel a sense of ownership over their own parts of the wiki.
Don't get hung up on formal process notations unless you are planning to turn them into software / workflows.
I have done some of my most effective work with pen & paper / flipcharts. For documenting more formally Visio / Smartdraw or other simple diagramming software will do.
Techniques: soft systems for the big picture, use cases to identify processes and actors, activity diagrams with swimlanes for the actual processe.
Agree that somone outside of the process should be lead the documantation as they can ask the dumb questions.
Don't try and document all proceses - use a riak assesment ot identify key processes.
As for keeoping the documentation up to date -how often do the processes change? If they do change as part of a project ensure the project is responsible for updating the documenation
Once models are signed off make sure they are available to those who need them. If the only person who knows which folder they are in goes under a bus you have the same problem!
Good Luck!
"I deny nothing, but doubt everything." Lord Byron
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 normal.dot 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
Moderation Total: -1 Troll, +3 Goat
I find paper airplanes work rather smashingly! ;)
Lodragan Draoidh
The more you explain it, the more I don't understand it. - Mark Twain
Document the STRUCTURE.
A comprehensive org chart that clearly shows who is responsible for what areas is all you need.
Then detailed job descriptions for each person on the org chart completes the task.
These are updated every time you hire, fire, promote or retire someone, at the bare minimum.
Then, once you have that, everyone below VP level should cross train at least two people at similar responsibility level to do large parts of their job, and train one or more subordinates to handle individual tasks.
Animoog.org
Sure, yeah, Wiki. Wiki is good.
Except when implemented like here. I work at a large IT company, and there are two chief complains against our official wiki.
1) access. Access to everything is denied by default. You get access to beginner employee documents, corporate standards and to whatever your team is doing at the moment. If you want access to docs on any tool, subsystem, API, service, function - whatever internally developed technology you need to use - you need to apply, through your boss, to the person responsible for giving access. You get the access the next day, unless the person is away on a leave/holidays (there's only one). Search returns only titles, so you need to guess which of the entries the search returned you need access to. Usually it's faster to rewrite it from scratch yourself or reverse-engineer the sources (you have access to these), or to find the author (by word on mouth) and ask directly.
2) keywords. A common habit has it that most internal systems get 3-letter acronym names. Amongst all, it's an official requirement to obfuscate the name so that competition couldn't figure out the function of a system from its name. And of course the search function of wiki requires searchable words to be longer than 3 characters. Ooops.
45 5F E1 04 22 CA 29 C4 93 3F 95 05 2B 79 2A B2
...start by not calling it Process Documentation. I see that and my brain wants to turn off. Likewise with "best practices".
You could look at using tools such as IDS Scheer's Aris, or IBM's WebSphere Business Modeler. These allow you to capture and document processes in a way that goes well beyond anything you can knock up in Visio or a Wiki.
These companies will be only too happy to provide you with consultants who will help you use these tools within the context of a process modelling/documentation exercise.
All you need are deep pockets.
I work at an employer with over 20,000 users in this region and everything is passed on by oral tradition. Every few years I have to reverse engineer something or reinvent a couple wheels because someone leaves or gets fired.
I can't say I'm any better. I'm stretched so thin that my documentation for my projects is in the source. No documents, no comments, no nothing. I haven't even had time to set up something for versioning or a simple wiki to throw notes in.
The folks who say that people won't cooperate are right - IF yours is an organization where people don't feel valued. If they don't feel valued then they will be afraid of being replaced. But if they do feel valued then they will understand, accept and believe that documenting their processes helps both them and the organization. And they will cooperate.
So first, you have to work on the culture.
Once you've got that in place, then look for ways to demonstrate that being indispensable sux. Anyone who's gotten that 3 a.m. call or who can't really take a vacation knows what I mean. Once you've been in that position, you really, REALLY want your processes documented so that you can take a real vacation and other people can do your job while you're gone.
Getting some sort of knowledge base / business process repository off of the ground is extremely hard to do company-wide. I started as 'The IT guy' 4 years ago when there were only 12 of us. Our employee count has ballooned out to 150 since then.
About six months ago I rolled out a plan to start documenting business knowledge. We used Sharepoint Services 3.0 - not the best knowledge base, but it's what we had available.
The knowledge base has been a huge success in Marketing, IT, and among the Executive Team. It has been a total failure in Customer Service, Shipping and Receiving, and Accounting.
In departments where it was a success, it was partially due to:- Department-level managerial support
- A manager who could spend some one-on-one time to understand every individual's responsibilities
- Having at least one employee in the department who actually sees value in process documentation. (As a side-note, these are the people who are ambitious to take on more challenging responsibilities)
- Communicating with the department when new knowledge base articles are created
Departmental failures were caused by:- Lack of managerial support
- Small department size. (There are only two people in accounting. We don't need to do this)
- A manager who is inherintly disorganized
No matter which knowledge base you choose, starting is the hard part. Ironically, I only got the buy-in of the executive team after a few months of using the system, and they offered a budget to get a 'real system'. I don't have time to spend on it, so I'm leaving it as-is. The content can always be ported into something more suited to the job, but Sharepoint works for now.I spent over ten years in the non-profit world, rising from systems analyst to IT director. If you are interested, feel free to contact me. When I started, things looked much as you describe. When I left, things were completely different. Largely this was through a process like the one you are contemplating.
I would say this: technology is not your friend here. It is a tool, and where you don't need it, don't use it. For example, if everybody is in the same building, talk to them in person rather than via a wiki. If you have fifty offices spread across the globe, then use the wiki. Remember wikis and such are systems, and you have to maintain them.
Also: remember that initially you are documenting in order to destroy. If you don't document to destroy, all you will end up doing is ossifying the current way of doing things, and IT will have to have a system function for every redundant and pointless step. In most organizations, there are many "reports" that are not really reports. They carry data from one step of a process to another. Therefore they have no intrinsic value in themselves. If the process can be streamlined, the need for the "report" goes away. And in most cases processes need streamlining badly.
The business processes that are in place evolved as the organization grew and functions split, through a series of local optimizations. People involved in the process know what comes into their inbox and out of their outbox, and that the people on the outbox side are complaining because they want things that haven't reached their inbox yet. They don't know where stuff is ultimately going, or whether they even need to be part of the process.
Therefore, in the initial stages, when you look at a business process, the things you must get right are: (1) what the process accomplishes, (2) what the inputs to the process are and (3) what rules (legal, ethical, professional) are fundamental to handling those inputs. As an example of the last, any time a check comes in, it has to go to accounting to be immediately cashed, not only for cash flow reasons, but for security. The kind of thing that happens as processes evolve from one person doing fundraising and bookkeeping to separate departments doing it is this: the fundraising person needs to confirm at some point in the process that the check was received, so he staples it to the form and puts it in his in pile. This was fine when he was also the bookkeeper, because he wasn't going to cash the check until he was done with that pile. Seriously, I've seen situations where checks were passed from hand to hand for weeks before they were cashed. This violates a number of business and accounting principles: not only does this put unnecessary strain on cash flow, it presents a serious security risk.
The way you destroy the old process is politically sensitive, which is why a wiki is a bad idea if you can avoid it. It's very easy to be passive-aggressive by simply not contributing or sniping. The reason for this is that people haven't really tried to fix the business processes beyond getting them to the point where they don't spontaneously combust. Such processes work very slowly, poorly and laboriously, and as a result everybody is under pressure to move things from the in box to the out box, which given the way the systems were "designed" it is certain they can just barely do. Therefore they don't want somebody walking in and telling them things are going to be tweaked, unless it is them that is doing the tweaking.
So, this is how you are going to create your documentation: you are going to interview everybody for whom the system's products are important, in order to determine the purpose of the system. You are going to interview everybody who participates in the system and write down what they do, with an eye to showing how it connects to other people in the process. Then you are going to prepare your description of the system's purpose, inputs, and outputs, along with a diagram showi
Post may contain irony: discontinue use if experiencing mood swings, nausea or elevated blood pressure.
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).
I would have a few people take the HP ITIL course. There is a short course that would be great for decision makers in your company that would be great. They would really see the benefits through a great simulation. The longer course will get you certified in ITIL. Its a 4 or 5 day course and you take the test on the last day. It was awesome. If you are looking for a good document repository that is cost effective, I would look at Knowledge Tree. Its an open source application that you can start to use for free if you have the expertise to set it up on a web server yourself. Alternatively you can pay them to host your documents or pay more for them to setup and support their app on your own infrastructure.
I run a small engineering services firm that is often required to provide our quality procedures as part of the vendor qualification process. I see no reason for our company nor a non-profit to pursue ISO 9001 certification yet the procedures and methods spelled out are very useful even in small organizations. We have implemented many of the business process and QA procedures using Alfresco, an open source content management system. Once set up, it is easy to use and integrates well with Microsoft/Mac/Linux desktops and email clients.
It's phenomenally important to ensure your documentation is written accurately, coherently, uniformly, and is organized properly. If you ask 50 employees to contribute tidbits to a common repository you're going to wind up with a shoddy patchwork - 50 different voices, assumptions of prior knowledge, steps written in paragraphs instead of points, and worse. Don't underestimate the importance of a professional Technical Writer to write or rewrite your standard operating procedures.
Well-written docs are inviting and reliable. Each time an employee helps himself instead of asking a peer or manager it halves the cost of that issue. Technical Writers don't cost you money, they make you money.
My [kibbitzing] advice is to them to document their accomplishments in an semi-formal team (b)log, not subject to continuous management review, with an emphasis on the solution of problems that they've encountered. This will help them detect similarities between problems encountered in the past, and maintain a sense of the value of their work. Focus on the sharing of best practices and needed information between groups, rather than how the institution might most easily transfer worker value from one person to another. (That's scary.)
My thesis is that enough contextual information will be obtainable, by someone perusing this log, that they will be able to replicate best practices after a relatively short experimental period. Nobody needs a detailed procedural description of how to mop a floor; but from some perspectives, in some roles within the institution, this might seem exactly like what you're asking for. And even if they write it for you, they know - everyone knows - that no-one don't really needs detailed instructions to figure out how to mop the floor.
On the other hand, I found a note to himself that one of the day-shift guys, Jerry, had left in the staff-room, and it totally revolutionized my fundamental understanding of the entire procedure: "fill bucket from kitchen tap until slop closet plumbing fixed."
If management is serious about this, they should practice and find best practices for the process of documenting processes itself at their own level itself before they dump it on anyone else.
When I started working for my current company, I was not surprised by the complete lack of accessible documentation. I got support from management and set out to fix that. I found Trac and starting experimenting with the Wiki. Then I discovered that another operating group in the company was also using it, but just for the SVN web interface. That made the choice really easy and my group is now using both SVN and the Trac wiki and it's working great. Because of the tight integration, I can edit scripts and programs, check them into SVN, then make a link into a Wiki page in Trac to add the supporting docs and other links. It's really slick and has helped our group a lot. I can't tell you how many times someone asks "Does anyone know how to do X?" and the immediate answer is "It's in the wiki, search for X", or we just email the link to the wiki page.
Also, it is very useful to have a convenient way to version control your important files and SVN is fabulous for that. If you use Windows, there is a great tool to integrate SVN into the explorer (TortoiseSVN) that makes it easy for everyone to use version control.
I had to champion this and added most of the original content of the wiki myself to get it useful enough to get the other DBA's interested in it. We had a number of advantages -- an existing installation, small operating group of relatively new people, lot of trust in management, etc.
Getting a first draft, however bad, out for review is critical. There are few people comfortable writing first drafts of procedures. Everyone literate is willing to comment and suggest improvements. I like http://www.atlassian.com/software/jira/ as a vehicle for organizing input, if you have the money. twiki.org is also used here.
Big binder that no one reads: - Keep it concise and simple and let the user find more details if necessary No one updates this crap and so it is useless: - Make sure everyone has access to keeping the information up-to-date. Give people credit when they update the processes. Keep version history of processes. Most of all, ensure that the interface can be updated from anywhere and from any machine in any geographical location (esp. near the areas where the processes are in use). I find wikis better than sharepoint in that aspect. Wikipedia is a good example of a solution.
Well in our innovative company there was such a huge turnover of staff, we were reduced to rumaging round in old emails to find out how or why a particular configuration was done that way.
.. straight out of Dilbert .. :)
We once got a contract to put a fashion house on the Internet only management forgot to tell us techies about it. They did remember to organize a big do for the designers and models to which we weren't invited to the do. We had to read the trade press to find out in which 'direction' our company was going in. Talk about a lack of communication, I know
davecb5620@gmail.com
The main problem you have is user education.
I first gained some support from the CEO on implement few policies:
1./ New hires will take my IT moodle courses and need to pass them within 6 months.
this courses have all related to understanding internal IT management.
After some turnaround, the effects show, and this gives me more leeway for implementing my ideas.
2./ Include training in project management, a tool that may help several is basecamp, so easy a monkey can do it.
Then start improving some other little processes, take on stuff you don't need everybody to agree upon, when they see that that works, then people will start to buy your ideas and you'll start modifying some other major processes.
The problem here, (and mostly everywhere), is the users.
Good luck,
-----
no sig
Our company had a similar issue. The other problem was, once the processes weer documented, people would randomly change the information in the document, causing even more chaos. Sharepoint can be configured with AD access groups and such, so that only management can have modify access, and everyone else can be read only. It also supports file versioning, which really helps to see what has changed from the previous version of a process. It also was extremely helpful during ISO certification. There was a bit of a learning curve and employee resistance to change, but it has been a year now, and everyone uses it like a bible. You can also add company forms, a company calendar for events, etc. I know that Exchange 2007 has much better integration for use with sharepoint which makes everything a lot easier. As far as getting to that point, simply determine what parts of the process are "correct" and document the hell out of it, using screenshots if possible. Test it with someone in the office who's never done that particular process before and see if they can complete it with your documentation. If they cant, you missed something. EVERY process in the building, from entering an order, to how you process your material should have a documented process.
We have a wiki. It works very well for us.
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 said...it'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.
Truth is like the sun. You can shut it out for a time, but it ain't goin' away. - Elvis Presley (source: imdb.com)
...is to assign the documenting job to someone who can type it up in Hindi.
rj
In my IT department, we usually document a great deal of information. The things we are documenting are results from our data processing, and endless running of queries and VBA/SQL statements. What we -aren't- documenting is the process in which these procedures are carried out, and all for one main reason. It makes our jobs more valuable, and therefore, us more valuable to the employer.
If you don't have a solution in mind and ready to try out, you ain't got much. Of course you have to sell management and staff on it, but THEY don't know what the best solutions are. So the reasonable answer is, talk to some of them, show them a Wiki, explain to them how it might work. Now you may end up with a somewhat different solution than you originally thought. You have to be flexible and it is quite likely other people's ideas are going to improve on yours. But if you go into it with no proposal at all in mind things are going to be all over the map. This is part and parcel of the common misconception that IT solutions in general should start out with a top down problem analysis. It is a nice theory, but it doesn't work well in the real world. The magic is really having someone who is both technically savvy (they don't have to be a tech guru, just well aware of the available solutions and what types of problems they best address) and also skilled at both listening to what other people want and what their ideas are, and synthesizing and articulating a coherent vision from that. AND you gotta be organized enough to manage pulling it off, etc. Ever wondered why the percentage of IT projects that succeed is small? Now you know, it often requires a pretty rare skill set to pull it off. Of course the better overall your organization is at putting together the right people to do that magic, the more things they'll succeed at. Regardless of anything else you have in terms of strengths and weaknesses, the one I think is really key is to be able to listen, and be flexible enough to accept what you hear and act on it.
"Malo periculosam, libertatem quam quietam servitutem." -- Jefferson
Whatever other steps you take, please be sure that your process documentation is published and announced to people in the company and even go over it in a presentation to all staff. Nothing is worse than a committee or working group creating a bunch of process documentation for processes that maybe never existed and then never telling anyone about the documented process until they violate the process. I just went through a year of hell with newly created and documented processes that sat in an obscure network share and were never told to anyone until an offense against the process was performed. Then it was roadblock after roadblock because "this is out of process". Inevitably, my response would be "do you mean a documented process? because I've never seen it documented or been told that it had been"
I've seen a lot of responses here on why (or why not) to docuement a process, but I think the original question was more about "how" to document a process.
Without going into a mind-numbing level of detail, here are some initial thoughts:
1. Processes are generally either transactions or transformations. In a transactional process, two parties exchange things (items, services, money, etc.). In a transformation, you take certain resources (parts, money, skill, time, etc.) and use them to create a product (car, computer, software, legislation, etc.)
2. Basic process modeling (which is based on classical General System Theory) deals with four main areas: Inputs, Outputs, Mechanisms, and Controls. In essence: what goes in, what comes out, what tools we use to change what goes in to what comes out, and the rules that govern our work behavior while do the changing. Your documentation should cover at least these four things, particularly for tranformational processes.
3. Use both text and pictures. Defining a process means agreeing on a common lexicon. The word "requirement," for example, cannot mean different things to different people if you expect a consistent result. Define everything in plain text first and only then start drawing relational or flow diagrams.
4. Outcomes and ouputs are different. An output is generally an object (physical or virtual). Outcomes, on the other hand, are based on expectations. You can produce an output that does not meet the expected outcome of a process. In this sense, outcomes are generally more important, as simply producing an output that meets technical specifications may not solve the business problem it was intended to address.
5. Don't get tied to one way of modeling or one modeling tool. Most complex processes will require a mix of modeling techniques. I recommend the following subject areas as a start: Unified Modeling Language (UML), Critical Path, Queuing, Interactive Computer-Aided Manufacturing (ICAM) Definition (IDEF) Languages (in particuler, IDEF-0 and IDEF-3), flow diagraming, Object Process Methodology, and the Zachman Schema. Some of these have specific uses and others, like Zachman, provide a more of a general framework.
6. Finally, start small. Don't try to do a gigantic process all at once. Break it down into its component activities and, within activities, specific tasks. It's like eating an elephant: one bite at a time.
I'll add at this point that I started seriously studying process modeling about 14 years ago and I still learn something new at least monthly about the subject.
The most frustrating thing you'll encounter is that it can take many hours to fully model something that many people can do without thinking in a few seconds. If you want a fun exercise with a relatively limited set of variables, try modeling how a football quarterback makes a decision on a pass play with time routes between four receivers who all potentially come open in a particular order within a six-second period.
Hope that helps.
TLR
A man no more knows his destiny than a tea leaf knows the history of the East India Company
The ISO 9001:2000 standards were meant for just this. So instead of trying to reinvent the wheel you may want to look into these standards and practices. If you break it down and look at it, it is just common sense management and addresses a lot of the question or questions you may have. .All you can do is make sure that your area or what you control fits within those standards to the best of you ability . Because your organization may not value time spent on documentation, you may just be hurting yourself. In which case you should just document for yourself.
Give certain people responsibilities for certain areas
Create documentation for those areas. Business rules and process documents.
Make sure that your Business processes and business processes are aligned with the company goals.
There are some ISO standards which deal specifically with IT. You might want to look at some of the CISSP books which deal with failure analysis. But the ISO standards and information is pretty much a management tool that will deal with the whole organization.
I have personally used the ISO 9000 Quality System Handbook and found it satisfactory.
But as many people pointed out, if top management doesn't want it to happen, or isn't for it, then your beating a dead horse. It just doesn't work. I've been there, seen it done it. I've also seen where people have shot the horse by following with strict adherence to the Quality Management System ignoring the part 'Top management shall ensure that the quality policy/system is appropriate to the purpose of the organization'
He who said 1,000,000 monkeys on 1,000,000 typewriters would eventually type the great novel, never saw an AOL chat room
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 the way -- the second best tool for knowledge capture is a cocktail napkin.
The first best tool for knowledge release is the cocktail itself.
At my business place we use an all in one intranet site built off of jivesoftware.com Clearspace. Clearspace is not just for IT though, it allows spaces of collaboration in all sects of your company. In Clearspace you will find blogs, wiki document/discussions, and in newer versions to come even xmpp. The spaces allow you to comment and add material with other people, trust me is a wicked tool to be using intra office. The software company I work at has an incredible short release schedule, nicknamed the release train, and this tight schedule could not be managed without a comprehensive tool. If you are interested at all in sharing knowledge on a new level, you must check out jivesoftware.com.
The process diagrams where I work are wonders to behold. Blocks scattered about with arrows flying everywhere to and fro. It looks like the Persian assault on the Spartans. The arrows blot out the background.
I love how some of the Final Assembly Process arrows feed *into* the Preliminary Design processes. Must have something to do with salmon mating season.
Heh heh...
You know... swimming upstream...
Heh?
Ah, the hell with ya.
I came here expecting the job security, "if no one knows what you do, you can't be replaced," with the reply in mind, "if you can't be replaced, you can't be promoted." I'm glad to see both ends of that conversation are well covered.
I'm prompted to reply in response to the, 1. increased efficiency, 2. ????, 3. Profit! posts.
As an American worker, increased efficiency is not my friend. On the lowest level, if I can get 8 hours of work done in 7 hours, I can spend that extra hour on slashdot. On the corporate level, all that increased efficiency goes straight to the top.
The USA has the best trained, hardest working, most efficient work force in the world. We also have an obscene and ever-growing gulf between the haves and the have-nots, the widest margin between executive and worker pay, an economy where the two-income household is the norm, where having one parent stay at home to take care of the family is a luxury.
It's called trickle down economics. The benefits go to the fat cats at the top. And folks below them get trickled on. Now I'm not a communist, and for the most part the fat cats at the top have worked to earn their position, but I don't see how increased efficiency helps me.
Yet I'm still on the side of doing this documentation. Why? Because it's the right way to do business. If you're in a low skill McJob, you are replaceable. Refusing to standardize and document your procedures isn't going to change that. If you're a skilled worker, documentation is going to complement your skills, not diminish them.
So how to do it? Do it. The best way to get management support is to show them a working pilot. Start with your group or your department. Don't just document your policies and procedures, but remember the meta-documentation--document the process of producing documentation.
wiki
Wiki's work well as grassroots efforts. It empowers the operations people to get things out there and not have to wait for others.
A reasonable formal way of documenting process, ensuring repeatability is the CMU software engineering institutes Capability Maturity Model CMM and/or CMMi. It's work at least doing some reading on CMM/CMMi even if you don't implement it in order to know what is available.
I haven't worked for a company that had much in the way of process documentation for almost 10 years now ... but that could be because I choose to work for startups and on open source projects, both of which tend to fly a little by the seat of their pants.
... hmmm .... wonder who's on top of that one?
Process documentation became a lot easier to face when we adopted a species of Agile and applied it to our everyday work. Allowing those processes to guide us has taken a lot of the required negotiation between teams and roles out of the picture and eliminated the need to document some of the more mundane first-do-this-then-if-you-encounter-that-do-this kind of tedium that can bore a newbie to their core. Plus, I've been lucky enough to work as the writer embedded in teams of developers for many years, so there is little need to negotiate who has what and why aren't they sharing it - we all know who has what and how to get it from them.
I've never seen the 'if I document this well, they won't need me' situation, but I have seen the situation where a consultant/contractor comes in, does a great job, but doesn't present a leave behind document and I find that slightly despicable. Leaving behind the guide to what you did only makes me want to hire you again.
I have to agree with many of you that wikis are an absolute godsend. No one wants to spend time documenting how to do their work when they could be doing the work, but they will do a quick wiki modification when prompted. Plus, since we can all challenge each other's processes in the wikis, it makes for a little competition as we write them and that doesn't hurt our performance one bit.
In short, relying on the wikis and day-to-day communication has ensured we have to support a remarkably limited amount of process documentation.
Now, to tackle that hit-by-a-bus problem
Virginia
...it has been used by someone else to understand and carry out the process it is supposed to document.
This is the same as "no code is reusable until it has been reused."
Far too many shops think that "documenting" something means writing the document, period. In fact, that's a necessary but insufficient condition. Anyone who has come in to a new shop and been told "here's our system configuration and build document" and tried to actually configure their environment and do a development build of the software knows that about half the time the document is either radically incomplete (with remarks like, "secret sauce here") or so outdated as to be useless. They eventually get their environment up with the help of the friendly folks in adjacent cubes, and forget out it until the next new hire comes to them for help.
I've seen this happen in ten person shops and in Fortune $smallnumber companies.
Ensuring that documents have been used is as important to documenting processes as writing the documents. Otherwise, no matter what you do, you will wind up with useless, out-of-date "documents" that have a high cost and low value.
Furthermore, the document should be updated (or at least reviewed for update) after each use, either by the person who used it or by a manager in conjunction with the person who used it.
This cycle of "write, use, update" can be introduced fairly painlessly as people turn over, and it can be made clear that it is part of the training of new hires, not an attempt to make existing employees more easily replaceable. In any case, all employees today know they are out the door the moment the CEOs six figure bonus is threatened, no matter how vital their knowledge is to the company, so their is not added risk to their jobs from having processes well-documented.
Blasphemy is a human right. Blasphemophobia kills.
My advice - don't "formalize" your processes.
The PHBs will do this:
1. they'll hire a big consultancy to tell you what the best way to formalize things will be,
2. they'll then recommend to start up a big huge group of people responsible for the process of formalizing the processes, and then
3. you'll then have to create a bunch of auditors that will then run around continuously checking that what you are doing matches what you said you would do in the formal documentations.
Of course this is all overhead, and when you establish your "ministry of process" and prioritize their work, their work will take all precedence over any real work. Your business will gradually grind to a halt as productivity goes backwards under the weight of all the processes.
It's a big project but that doesnt mean you have to do it all at once.
I would think there are three information stores you will want to have
1. confidential - this iss all the stuff that you want in a safe, passwords, access numbers accounts, etc. This should be a high priority to gather all that stuff just in case someone with exclusive access to something get hit by a bus.
2. general - If there are regs and manuals, etc for something they should be somewhere where people can find them (you don't need to put a procedure to change the staples of the copier in your procedure manual but you darn better know where the copier manual is).
3. Specific - this is the stuff specific to the company or position, like what to do when there's a utility problem, how to create new promotional material (who to talk to, what are the design guidelines), etc. This is great for a Wiki, also if there are levels of need-to-know use a wiki with access groups (Dokuwiki is one) plan your structure, just don't throw everything into one section (part of the access group thing, also for organization)
Start your Wiki with:
a) stuff that generates the most emails, memos, or general confusion (agendas/minutes, conference room schedules)
b) procedures that get people in trouble if they do it wrong in any way (procurement procedure)
c) information that changes frequently that staff should have immediate access to (staff directory)
build from there. Having those starting points will get people to at least access the wiki early on, may not get them to add to it right away, but as they get used to the concept they will see how useful it is.
"Enjoy what you're doing! If it becomes drudgery, you're doing it wrong!" - Jim Butterfield
Here's how I'd do it:
1. Identify key personnel and ask them for basics of the process
2. Research existing docs and look for "holes"
3. Interview action personnel to find out how things are actually done
4. Set up a base document, and document tree
5. Design a standard template and language
6. Write a draft
7. Get buy-in from legal and management
8. Ensure that someone or some role is there to update this and revision it.
All of these steps are important.
It is useful to have an experienced professional, -or- to take the time to learn the basics of process technical writing, which is like all careers not rocket science but requires some study and experience.
It is really helpful to have a role or person whose job is centered on this task, as then others are more likely to allow them to poke around and ask questions, and they won't destabilize existing office political arrangements or get anyone fired.
Tech writers always need to be the neutral third party under such circumstances.
technical writing / development
I work at a 2000+ person engineering nonprofit and volunteered for the process committee. We're still working on it and will be for the next year or 2 at getting our development processes to reach CMMI level 3. My experience has been that document repositories like alfrsco, documentum or e-room are better accepted by management than wikis. I love alfresco personally. That being said, look at the stuff on the CMMI website at Carnegie Mellon and buy IEEE standard J-STD-12207.0 for software lifecycle workflows. Ultimately, the only way to make process work is to get total buyin from everybody from the CEO all the way down the the button pushers. You have to convince people that writing down a sane way of doing something and making a social affair of discussing the way you do things regularly is what they ought to be doing. As soon as people see process as a burden rather than a way to get rid of inefficiencies and things that bug them, they won't cooperate. It also appears that one needs a couple of full-time people to make sure that it's happening and to update the processes. If you don't have people permanently assigned, it rapidly degenerates to an electronic form of the binder full of crap method. Best of Luck!
Thanks, that made me laugh :-)
Insert
Let me join in with those who have mentioned the value of modeling your processes as opposed to merely documenting them. A model is a testable representation of your processes. You can take the output of a model and prove that the system it describes is consistent and complete. The information you put into a model can be reused, analyzed, transformed, and distributed where it's needed. Documentation only gives value to the (very few) people who will actually take the time to read them.
In terms of what notation to use for process modeling, you can't go far wrong using Business Process Modeling Notation (BPMN). Using a standard like this will save you tons of time and effort. There's no need to reinvent that particular wheel.
Regarding tools, I'm a big fan of Enterprise Architect because it is inexpensive but comprehensive. Contrary to some of the advice in this thread, I don't think much of Visio as a modeling tool. It's really for drawing pretty pictures, not making models. Microsoft has some very nice modeling features built into Visual Studio, I believe, so if you're into Microsoft, try those tools instead.
Best of luck.
"We receive as friendly that which agrees with, we resist with dislike that which opposes us" - Faraday
Social Logic will help mitigate obstacles. Technology Logic as infrastructure is a partial solution. Business logic only, will fail.
...). In the work environment infrastructure (significant, maybe complete) community implicit content can be collected, grown, and maintain then mined, recovered, and recycled for business logic purposes.
... data/content bulk collection and Biz and HR essential information ... it should be possible to initially chart the conceptual ideal core-biz processes to core-personnel, then to external B2B/B2C processes and their essential contact information. All along this flow/path the core data/content bulk can be used to convert internal into explicit codified knowledge publications. Then, you must maintain the data/content bulk/audit trail to discover innovative, transitional, and situational variations in new implicit activities for intelligently transition of explicit knowledge publications and future BizTransformation (why, because shit happens and things change, thank god).
A community (Social Logic) is always sharing implicit content to sustain the social relationships (work, pay, play, safety
With internal VoIP, email, PIM+, web-browsing history, VTC/Social conferencing, BioPKI tokens/authentication
Tools to consider as part of the solution:
CMS, Syntax: http://en.wikipedia.org/wiki/XML
CMS, Syntax: http://en.wikipedia.org/wiki/Syntax
CMS, Syntax: http://www.w3schools.com/
CMS, Syntax: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=XML
CMS, Syntax: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=Content+Management+System
CMS, Syntax: https://sourceforge.net/services/buy/service_providers.php?words=XML+schema+syntax+
KMS, Semantics: http://en.wikipedia.org/wiki/Semantic_Web
KMS, Semantics: http://www.w3.org/2002/ws/swsig/
KMS, Semantics: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=Knowledge+management+system
BPM, Semantics: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=Bussiness+Process+management
BRM, Synergy: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=business+relationship+managemnt
RMM, Synergy: https://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=relationship+managment+model
RMS, Synergy: http://nwn.blogs.com/
RMS, Synergy: http://secondlife.com/whatis/
TCM, Practical: http://www.sei.cmu.edu/isis/model-problems.htm
TCM, Practical: http://www.sei.cmu.edu/intro/documents/concept/
TCM, Practical:
Unaccountable leaders are masters, and unrepresented people are slaves. How do US and EU fare?
Preface: I got called away after I started this, this is quick and dirty, and I'm pressed for time, but it's my hope that it will act as a starting point for discussion. I'm sure there's many opportunities for optimizations and there are shortcomings.
How to come up with process documentation? For starters: have the processes document themselves; i.e., add a wrapper program around invocations of common applications which captures:
I'll assume you are working in a Microsoft Windows/XP shop. If you haven't already, get a copy of the GNU CoreUtils for Windows.
Set some global environment variables for each user and then code a simple batch program, logger.bat:
That would produce data like:
Now, wherever a user ordinarily runs "foo", replace it with a call to "logger.bat foo %*" e.g. Update items in the start menu to invoke logger.bat with what you'd ordinarily run.
Crude? Yup! Sufficient? Nope! Maybe you have a better way to do it... Good! Maybe you'd prefer to do it in perl. Fine! What about phone calls? Well, can you extract logs from your PBX? Gather that data and merge it in, too!
Here's the important thing: It does not require any change in what the user does in the course of their day, it is easily extensible in that you can instrument other apps to log as you find them, and most importantly, you now have some data to start from! As you find gaps in the day's activities, instrument those, too. The good part is that it does not "cost" much in your time or the users and it will go a long way to getting started. Don't believe me? Try instrumenting what YOU do and see if you can find any patterns. Refactor it. Lather. Rinse. Repeat!
Now, using the data you've gathered, you can write filters to extract who touches a given file as it works its way through the system. Or, get a look at what applications somebody uses each day. Dependencies will reveal themselves.
There's lots of good advice here. The one thing I'd add is: document it the way it's done, not the way you think it should be done.
In the process of documentation, you will find stupid processes. Resist the temptation to change them while documenting them. If you really want to waste a lot of time writing docs no one will use, give in.
Process improvement is a separate task. It requires a whole different attitude, a whole different level of buy-in...
'In knowledge is power, in wisdom humility.'
Just read your organization's standard process documentation process and do what it says.
I too used to work in the nonprofit sector in IT. I believe you are headed in the right direction with your project. Here is what I suggest - remember your audience. If you are trying to increase professionalism and decrease the chaos for nonprofit workers - give them a tool they can understand and find value in. Try out a Wiki - nonprofit workers are, by nature, people persons. They like to feel connected to people and prefer doing that to reading a big and potentially boring document. Sell Wikis as a way of reaching out to other people. Encourage them to find other concrete uses for whatever technology you pick, such as donor management. Again, remember your audience.
As you might note from some of the threads, the biggest problem is convincing folks who are inherently insecure to document what they do. There's a lot of "fence building" that goes around in IT and documentation goes against that thread.
Everyone needs to know that documentation is in their best interest. The best way I have seen this is by creating a tier support group, where all pages go to the tier1-2 folks. If they do not know how to solve a problem, then they page out to the higher level folks. They DO NOT need to be held responsible for tasks that are not documented, so it is in the best interest in tier-3 folks to document solving problems so they are not bothered in the middle of the night.
So don't start with documenting "everything", just the crap work. (IE: what do I do when this T1 fails?)
Later, when this starts getting traction, then introduce the same concepts to other kinds of work, where the Sr. folks get to do more fun stuff like testing/researching new cool tech's as long as their boring day-to-day tasks are documented so that the Tier2 folks can do their old work for them.
Also remember that code is also documentation. So if you can start getting repeated actions converted to scripts, then that as well counts for documentation, and it frees up staff for thinking big, rather then pretending they are robots.
You will always get push back, but if you frame the tasks as a benefit rather then a chance to loose their jobs, then things will work better.
The other thing to consider, is that if they are really that worried that they can loose their jobs, then chances are, they ~really~ do suck, and they might be telling you how unnecessary their work really is. Consider the phrase: "Go away or I will replace you with a very small shell script". Find the guys who will write the script to work for you. Not the guys who endlessly click the mouse and do not understand what they really are doing.
As far as software. Sharepoint sucks!
consider two paths:
1) wiki's:
http://en.wikipedia.org/wiki/Comparison_of_wiki_software
2) or revision control software:
http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
RC software would be the most flexible, and give you more control with script and controlling changes with them. Wiki's are just really easy ways for everyone to modify docs (no html skills needed, and the output is all formated the same way.)
Good luck!
Improving the process = making it more efficient = making it require less manpower = growth and increased competitiveness ... 'there, fixed that for you'. It's a common mistake to think that purposeful inefficiency leads to higher job security - your competition is out there each day becoming more efficient than you. It's better to work for a company that is better at what it does than the competition and grows, than at the company that eventually goes under.
Most company owners / shareholders want to see growth; if you ever hang around serious traders you'll pick up that. But that aside, I own my own business too, and (like most business owners) if we increase our efficiency and lower our training times, I would MUCH rather hire new people and grow as a result of that, in fact I can't wait until we can 'afford to hire more people'. Being able to eagerly announce to our customers and to the world that we are shrinking would be of the most boneheaded business move I can think of - that NEVER looks good, and makes customers jittery. Being able to announce "we are expanding" is great for everyone - it makes shareholders happer, it makes customers happier and feel more secure, it improves employee morale.
To add to the good stuff that everyone else is saying, I'd suggest that you try and start slowly and don't try and fix the world before lunchtime.
I'd pick one process where having something written down would benefit all of the users of that process, and try and get something down there (possibly as notes from a "passed on orally" session that was going to happen anyway.
Whether you use wikis, Sharepoint, Livelink, just a pile of shared documents or whatever is less important than making sure that the idea of keeping information shared has buy-in from as many people as possible (not just "the management"). I'm guessing that in a non-profit that's even more important than in a commercial enterprise.
Also, apologies for stating the bleedin' obvious but but you're new there - so the chances are that there are also a whole bunch of relationships between people built up around "helping person X do thing Y". You'll need to tread carefully to avoid making enemies out of the traditional "sources of knowledge" in the organisation.
If you get cast into the role of "the person who does the documentation" then it'll be your "fault" when something isn't communicated properly between two completely different people.
For the User/Developer, among the best are ... "Open".
Apache FOP: http://freshmeat.net/projects/fop/
Apache FOP: http://xmlgraphics.apache.org/fop/download.html
NetBeans: http://download.netbeans.org/netbeans/6.0/final/
Alfresco: http://www.alfresco.com/
Good Guide: http://www.vrcommunications.com/PDFs/ditaotug141-03122007-pdf.pdf
Title DITA Open Toolkit User Guide: Fourth edition, December 17, 2007. Based on release 1.4.1 of DITA Open Toolkit. All files copyright 2006-2007 by VR Communications, Inc., unless otherwise indicated. Licensing Edition, release, copyright and usage of this document and related materials is regulated by a Common Public License (CPL) granted by OASIS (Organization for the Advancement of Structured Information Standards), http://www.oasis-open.org/ . DITA Open Toolkit is an open-source, reference implementation of the OASIS DITA standard (currently DITA 1.1).
JAVA: http://www.java2s.com/Open-Source/Java/CatalogJava.htm
Open Office: http://www.2008-official.com/openoffice/
Unaccountable leaders are masters, and unrepresented people are slaves. How do US and EU fare?
K, I know this horse has already been pretty much kicked to death, but at the company I was currently hired at, I was originally here as a 3-month intern to document program flow. I was given a TiddlyWiki http://www.tiddlywiki.org/, which is a super-easy local wiki. It requires no setup, and anybody could figure out how to use it effectively in about 2 minutes (and that's factoring in stupid people). For anyone looking for a very small-scale wiki, or who don't have the resources to setup a full MediaWiki installation, or who just want a useful personal type wiki, I would highly recommend this thing. It's absolutely great!
We use Microsoft Team Foundation Server and Bug Tracker. As software developers, we couldn't do our job without it.
Many posts are correct that the challenge is sale and buy-in. I'll just chime in to agree that media wikis are transformative. Valuable documentation is documentation that is easy to find and kept up to date.
I've seen the following set up with little success at previous companies
Media wiki: Easy and cheap to set up. Easy to find stuff. Anyone can update to correct inaccuracies (or roll back incorrect edits). We combine it with a local Google search Appliance and I can find anything I need in seconds. I can't imagine documenting process, or anything else, in any other way.
My motto: "A cat is no trade for integrity."
I think the idea of using a light-weight, collaborative tool to gather "process" information is a basically sound, but merely establishing a collaborative environment usually is not enough to accomplish what you want. You can't just say, "here's your new documentation tool! Write down what you do!" I've seen many such pitiful attempts at "Knowledge Management" die whimpering; their naive sponsors never seem to understand that "knowledge" doesn't just happen. Here's what I'd do if I were you:
Great men are almost always bad men--Lord Acton's Corollary
Sometimes process is an impediment. Only take on the amount of process that you really need and require.
I work for a company that makes medical devices. We have strict process as required by FDA rules, manufacturing certifications, and a grab bag of other regulations based on countries we sell to. When we have a quality problem, it may affect customers and safety. My friend on the other hand works for an IT department for a large defense contractor, and the department's duties are to keep computers and networks running. Though it seems like they're focused on metrics collection to the exclusion of providing actual service. When they have a quality problem, the effect is relatively minor (someone has to manually perform an automated task and the VP gets a chart a few hours late).
From discussion, my friend apparently has to deal with far more process headaches than I do which seems backwards. Yet his department manufactures nothing, sells nothing to customers, and does not have to deal with outside auditors. For a project to tweak their metrics collection, all software pieces have to have a detailed design, and everyone must attend a meeting in person for the design reviews (apparently people never responded to email). Months are being spent on a relatively simple project, most of the time is spent in meetings, and documentation is rejected for not meeting someone's idea of how a document should look (you must use the right font, size, section layout, etc).
The difference seems to be that at my company our goal is not to create and follow a process, it's only a tool used to increase quality and satisfy requirements. By my friend's department seems to have someone high up in the chain of command who has decided that process is the most important goal.
My point being that you need to decide why you even have a process and decide how much of it you need. A little process is usually good, but a lot of process just gets in your way. Also process does not eliminate the problem of bad management; if your original problem of disorganization and chaos was due to bad management, then process will not fix anything.
Documentation is very effective if it focuses on only crucial parts (Unix man-page style), and is written in simple English (what I call "8th grade English").
You don't want to answer every imaginable question, or you end up with an unwieldy book. Describe the common cases, leave finer details unspecified. Give credit to your employees, a few common-sense people can find a solution to unusual problems; or, put a list in the document of people to ask for help.
Simple English is important for a few reasons. One, it's easier to read. Two, it's more accessible to non-native speakers. And third, it keeps documentation on task: the goal is to be helpful, not to show off. (Whenever I've seen a hundred-page file rife with 12-character words, it was written by people with superiority complexes; and no, the documents were never useful.)
"Microsoft killed my company, I hold a personal grudge. I don't use Microsoft products and neither should you."-JWZ
Basically, this is how it goes:
Every team or group in the company is made responsible for (a) writing down their own values and processes on a Wiki page and (b) listing their obligations to other teams. The former is called the "team charter" and the latter a "service level agreement". Tell them that they will be required to sign these charters and agreements later. They are of course allowed to cooperate with other team, e.g. the testers might need to create a common template, or talk to the software development team about their obligations. Make clear what you expect to see, then ask them to come to you to get it accepted when they're done.
Length, detail and quality doesn't really matter. One page of text will do a long as it covers most things. E.g. "We are software professionals and like other people's code to be well designed, well written, well documented and not too optimized. In return we will write our own code to that spec. [...] We believe that domain knowledge is improved by creating throw-away prototypes and mockups. [...] For defects we use Bugzilla; the guy who currently owns the Bug Fixing Hat is responsible for performing triage daily on the new bugs. For version control we use Subversion; the guy who has the Builder hat is responsible for creating fresh weekly builds..." etc etc.
Measure the number of teams that have posted their team charters and service level agreements in the Wiki. Give a small goodie (toy, bonus) to the teams when they complete the charters and SLAs. Post the number of teams and the percentage of all teams in the company's internal newsletter. When there are only a few teams left, post the names of these teams in the "hall of shame".
Pick a handful of random teams. Visit them and make them explain what they have written and the rationale behind it. Have they listed all team that depend on them? Are they doing stuff that's not in the charter? Does the charter contain outdated practices? If they say they're happy with the charter, print it and make them sign it. If they don't want to sign it because they're not done yet, make them update it until they are happy with it.
--Bud
... when your colleague could do it for you.
By this I mean ROTATION. People should not try to explain how their process works,
but instead work for a week or so on another post... and then explain what it was all about.
It's all well documented in System's Analysis and Design Methods. Problem is, no one wants to do things the right way these days. They all want RAD fixes - short term gains with long term losses.
You don't get what you don't pay for.
YMMV
Codifex Maximus ~ In search of... a shorter sig.
I develop software in a medical device environment, so we're ISO 9001 certified, follow FDA good manufacturing practices, our own quality system, etc. The only reason it all hangs together is there are people whose job is Quality Assurance. People who audit everything, and if we don't follow what we're supposed to then we get dinged: have to go to remedial training, have to sit through even more meetings discussing why we screwed up, and have to revise the procedures yourself if they aren't right. So the path of least resistance is to document, do it the way its documented, and pass the audits. This takes massive management commitment to keep in motion. We joke it's the CJO's(chief jailable officer)problem, but they don't think it's that funny. It's part of the bottom line. So in your case, unless you have commitment, enforcement, and punishment it just ain't gonna happen. I was in a company once that went for ISO certification from scratch. It took over a year to get there, a great and dogged commitment on the part of management, and a good chunk of resources to implement. Of course, it was for a government contract. What system is the best, how to capture knowledge, etc. are all sorted out in the planning meetings after the commitment is made.
This could help. Sorry, but I've not got time to sort out the HTML syntax on this crappy slashdot forum, but there you go - you get only what people can imagine... There is a "best" (i.e., proven) practice approach to BPR (Business Process Re-engineering) for IT operations. It is includes these points: * Good theory and defined "best" (proven) practice as a basis for rational action (there can be no rational action in the absence of theory): (a) For the management of IT processes: recommended is the international and pseudo-public domain ITIL (Information Technology Information Library). (a) A conventional Management of Change approach - Kotter's 8-Step Change Model. (b) A process capability model. The internationally used and general process capability maturity model - the Humphrey's CMM (a 5-stage process Capability Maturity Model) developed in 1986 as a tool to improve US Dept. of Defense software development contract-letting, by the SEI (Software Engineering Institute). The CMM, used as a *general* model for processes has nothing much to do with its newer sister-model the CMMi - which is *specifically* all about software development processes. * The approach includes, for example, process discovery, process definition (AS-IS and TO-BE), process modelling (preferably using a CASE tool). * A standards-based approach: IDEF: recommended are the well-established (1983), tried-and-tested public domain and internationally used FiPS (Federal Information Processing Standards) IDEF0 and IDEF3. IDEF was originally developed for the US Dept. of Defense, but has been used by many government depts. and commercial/non-commercial organisations worldwide - e.g., US, Europe, New Zealand, Australia, Canada. BPMN: the BPMN standard could be used, but that is proprietary to an industry consortium - it seems to have been set up in a classic self-serving manner - i.e., to develop a new (since 2003) standard that forces the user to buy the new CASE software developed and supported by members of the consortium. * Use of a CASE tool (highly recommended) for process modelling, as opposed to using "manual" diagramming tools such as Visio, Word diagrams or PowerPoint diagrams, for example. There are two main CASE tools that support IDEF0/IDEF3: 1. CA's Allfusion Process Modeler BPwin): supports IDEF0, IDEF3 (This seems to have been the leading industry product since at least 1988, and is relatively cheap. 2. Telelogic's System Architect: supports IDEF0, IDEF3 and BPMN. (This is relatively very expensive.) There are three main CASE tools that support BPMN - they are almost Aris and Aris: 1. IDS Scheer's Aris: supports BPMN. (IDS Scheer is a key member of the aforementioned BPMN consortium, and yes, it's relatively very expensive, of course). 2. Oracle's BPA Suite: supports BPMN. (This is just an OEM bundle of Aris.It's relatively very expensive, of course). 3. Telelogic's System Architect: supports IDEF0, IDEF3 and BPMN. (This is relatively very expensive.) Happy to help if required. This sort of thing is my bread and butter as a consultant. Regards, IainMSB.
If you go the route of a Wiki.
Look at http://www.brainkeeper.com/
The BrainKeeper Enterprise Wiki
All the collective knowledge of the people in your company, in a single system!
BrainKeeper's Enterprise Wiki Software provides a centralized knowledge repository that everyone in your company can use to capture and find your most critical information. We provide a whole host of features to make it incredibly easy to get information into the system, find the relevant information you need, and notify the right people when essential information is added.
I work for a company that does CMM, CMMI, SixSigma, LEAN, etc. However, I have not seen it actually improve anything.
I certainly do believe that certain CMM/CMMI stuff is very valuable and would greatly contribute to making software better; however, the documentation overhead it brings is a nightmare to manage and keep up to date. Honestly, I think we really need to do better with coming to a compromise to the overbearing documentation that CMM/CMMI systems bring and the chaos that typically at the other end.
Software does need to be engineered, and it does need to be done in such a way that helps think about the future...but you also have to balance with actually making the system practical to use - which is what I was trying to get at. The way people use LiveLink/SharePoint makes it entirely useless - sure, it solves the legal requirements, but it's not worth the cost of the installation disk it came on because it just tosses tons of info in without any real consideration for how to get it back out since the people managing it don't know beans about managing such data.
Well...I better end any rants there...needless to say, there's a balance that needs to be achieved.
Truth is like the sun. You can shut it out for a time, but it ain't goin' away. - Elvis Presley (source: imdb.com)
It matters that all the procedures have a traceable documentation on how to do them - including how to find the rest of the documentation - and that the employees know how to find the documentation they need for their job and to know that it's current. But the documentation can be on dead trees, backed-up filesystems, or the upper left corner of the whiteboard in Joe's cube.
Having the ISO cert lets your customers know that you can be counted on to produce more stuff of the same standard in the future. Whether it's high or low quality is between you, your customers, and your competitors - as long as the stuff (or services) you produce next month is no worse than what you were producing when you got the cert.
(Or at least that's how I understand it... B-) )
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
You have to get everyone in your organization to buy into the argument that documentation is important.
The way you do that is by pointing out that documentation makes everyone's job easier. Every employee can easily think of a task they slogged through the hard way that would have been easier with proper documentation. Every manager can easily think of a time an employee took 40 hours instead of 5 to do something because the employee had to teach themselves about someone else's area.
But documentation is still no substitute for people-power. Documentation just says how to do things, it doesn't actually do them. So all these fears about documentation lessening employee value are unfounded.
Moderator hint: a comment is neither "Flamebait" nor "Troll" if it is true.
First you must document the documentation process. If no one know how to document things, all will be in vain.
Here will be an old abusing of God's patience and the king's English.
I dont agree anymore about twiki needing perl knowledge, neither beeing hard to install anymore. I know you said "effectively....etc" but with the recent 4.2 version installing plugins from web interface, dependencies resolved its very easy. Configuration of settings is also web page. There was windows installers for twiki 4.1 and I think there will be for 4.2 also shortly. Do the vmware download or apt-get install twiki on Debian based distros. ,consultans for hire and also commercial like twiki.net. Check out the IRC applet on the suport page, brilliant. And the new wysiwyg editor is fantastic. Look at the testimonials and maybe ask existing users about real-life feedback. There are mainly grown up people using TWiki seriously either internally in companies or making a living off it as consultants.
TWiki is very well worth the time because you get awesome functionality.
I'm no programmer but have installed twiki many times, the things I spend time on is the pages; templates, use of plugins. Making good designed pages. Once that is done you can reuse it easily and after a while your end-users can create web forms etc themselves also. There is lots of help from community
I work in an IT organization of a subsidiary of a Fortune 500 utilities corporation. Our group has virtually NO documentation in an electronic or paper format for all of the source code and data modeling we have constructed over our 6+ years in business. Essentially all we have are a couple of Visio diagram that describe the data models, our nightly batch process from an essentially useless high level and a few Word documents outlining one or two not-so-business-critical processes. The real business process knowledge is distributed among the heads of the developers. Of course, several of our IT staff are nearing retirement age, so documentation becomes a critical issue.
I have personally recommended creating our own company wiki, as I believe that by allowing all employees the opportunity to document their work as they get the time and to be able to actively correct any incorrect documentation. Not to mention, an intern being paid 2/3 of the entry level salary could maintain the wiki with relative ease, saving the company much more money than adopting a Sharepoint solution (IMO). My IT manager and supervisor both would like to adopt the wiki idea, but being in a large corporation, we need approval from the right people to get it into place.
You are right in saying that your efforts toward documentation will fall short if management isn't actively supporting your initiative. My experience within Fortune 500 companies is that management will generally not put much emphasis in a project unless it provides business value that also benefits their earnings per share. Sometimes businesses focus more on capital projects and making money than process improvement initiatives (especially when it could greatly reduce the training time for new/transitioned employees or contractors), which have the benefit of bringing down sustenance costs.
Where I work we have thousands of pages of dead trees that get used maybe .5% of the time. Due to business constraints REQUIRING the use of IIS and Sharepoint we ended up going with OpenWiki and use Sharepoint for a document depository putting the links into the wiki. It seems to be working very well as people really like the search features. Plus, with active directory and the IIS configuration we can track who is making what changes in case there are any problems there (there haven't been to date). I would argue a wiki is definitely the way to go.
Avrice
People have raised a lot of good points about the obstacles you face. In situations where I've been in a challenging situation for documentation (people who don't have time to explain what they do, don't want to when they do have time, and even when forced do a lousy job of it because they're neither skilled as teachers nor fully aware of all the parts of the process that have long since become second nature to them) - he's what I've done that works pretty well.
First, to make it as painless as possible for the staffer - run a screen capture program on their machine while they walk through the process - describing what they do as they go. If the task takes place off the computer screen, bring a video camera as well. Go ahead and ask your "newbie" questions and let them answer. Be sensitive to when they've reached their limit for explaining things.
Then you (or whoever is genuinely good at explaining things to people) can go over the recording much more thoroughly - writing down the questions and/or misconceptions that came up and what you eventually figured out the answer to be.
One really important part of the process is coming up with "business dictionary". If someone mentions a "request order" or "line item" - you must know exactly what means before creating an explanation which uses the term.
All of the work up to this point illustrates why it's vital to have someone utterly unfamiliar with the process to creating the initial documentation. A seasoned employee of the company will fail to recognize where you and the staffer have used existing knowledge without explaining it - from terminology to small processes. A person unfamiliar with the specifics of the business cannot make this error.
Lastly - the procedural documentation must be created. In performing this task - you must recognize that different people learn things in different ways. Reading a Wiki will work for some, seeing an on screen demo will work for others. Keep track of when you documentation has not fulfilled it's purpose (conveyed all the knowledge of how to perform a task without being supplemented by the "oral tradition" approach); and enhance it as warranted.
Don't worry too much about updates. Someone with a firm understanding of how things used to be done is well positioned to be brought up to speed on any changes without needing a totally reworked set of documentation.
In general though, a live, narrated screen capture (or film) is both the easiest way for people to demonstrate how to perform a task (the only difference for them compared to a regular day is explaining what they're doing and why their doing it), and the easiest way for someone else to learn it (they can watch it as many times as they need to grasp any details they missed the first time).
The level of involvement outside people have should be dictated by the situation. A highly complex task which needs to be taught to someone totally unfamiliar with your whole industry must include a lot of basic information no one on your staff will think to mention. Smaller tasks which must be documented for people already working in the company can usually be handled by video demonstration created by people already on staff.
But just asking people on staff to document the processes they perform every day is a terrible approach. Making documentation is not what they do, it's boring, and they're pretty much guaranteed to leave out crucial steps which are obvious to them; or simply make small but critical mistakes and not realize it. If they're captured actually *doing* the task - this can't happen. They must go through each step, and either not make any mistakes, or correct them when they do. You just want someone else there to make sure that each action taken is explained (particularly important for computer based tasks where the actions on the keyboard (short cut keys, password-masked fields) cannot be seen.
Good luck.
I'm looking for a Wiki/Network mapping (Visio Style) application or CMS to document a whole network, servers, applications, services, IP addressing, and etc. Anyone recommend a complete cookie cutter system for documenting a network? Open source preferably? I am in a new systems administrator position and this would help me to not only document my work but to understand the systems and also not forget where things are. It would be nice to be able to click on items in the map and documentation to remote desktop or ssh into servers. I appreciate the input!
put to good use at tech companies.
Essentially, you make each team responsible for putting important documents on their wiki page, and make each team member responsible for documenting his particular project (design documents, howtos etc). The key thing is to make this easy to use, so test out various wikis and pick something with an easy to use syntax and interface and make sure there's not a lot of permissions nonsense blocking your users (they shouldn't need to get in contact with you to make new pages, etc). Also, having prefab pages that can be copy pasted to get the layout right helps (like a canonical design document).
For a less technical audience, wikis might be problematic. You should ask yourself what the average technical skill of your users are, and if most people aren't confortable with writing basic html, then they probably aren't going to be comfortable with a wiki.
Aside from that, a big directory for word documents isn't that bad of an idea. If you give every team their own share they can write to and make everything globally visible in a way people can pass around paths (z:\teama\mydoc.doc) then you will be using tools that people are already pretty familiar with. Make sure that the share is automatically mounted on the same drive letter for every machine, as users with low technical skill won't understand how to mount their own shares.
I know it's pretty unslashdotlike to suggest using word and CFS/SMB shares, but for users of low skill that's the simplest solution they can handle. Otherwise, go with wikis, but only if users indicate that they understand them and would use them in their daily job, otherwise you are wasting time.
The most important thing about any documentation solution is that people use it, otherwise it is useless. To minimize the costs of using it, I suggest you find a solution that is similar to something people at your organization are used to using.
I had the same problem land on my desk a month ago. All of our policies and procedures were stored in a big notebook that was horribly out of date and that no one read. Since we use Trac for our dev department, people were used to the wiki formatting on it. I installed MoinMoin as a corporate wiki, which uses the same format.
MoinMoin is great because it uses basic authentication from apache, so you can authenticate it against whatever you have (like Active Directory), and people don't need another set of passowrds. It is simple to use and also easy to backup. Also, if you have a corporate intranet already, it is not difficult to integrate.
The wiki is great because anyone can modify it without alot of fanfare. However, if you choose a solution that is yet another thing to learn how to use, no one will take the time to use it. Again, the most important thing in my opinion is to lower the cost to the end user so that it is easier to post the information on the wiki than answer the same question again and again.
My favorite is Proof by lack of counter-example.
I certainly do believe that certain CMM/CMMI stuff is very valuable and would greatly contribute to making software better; however, the documentation overhead it brings is a nightmare to manage and keep up to date. Honestly, I think we really need to do better with coming to a compromise to the overbearing documentation that CMM/CMMI systems bring and the chaos that typically at the other end.
In the mid 90's, I was in an organization that got CMM level 2 & 3 cert. I was on the team for both. What it really does is make people think differently. Not necessarily following all the incredible doc overhead to the letter, but it does actually help. For a while.
I left there, and came back 9 years later. They had completely forgotten what we had done. Completely and utterly forgotten. I'm slowly trying to bring those concepts back.
I've tried to evaluate a number of open source CMS applications for use at my pharma. company, but none seem to be Part 11 compliant out of the box. Sure, with developer time, some could be made compliant, but none of has the time to do it ourselves, the time to manage a software project, or the budget to pay for custom development. Typical business situation. Does anyone know of an open source solution which is Part 11 compliant currently?
Now in my opinion, EPF isn't right for everybody. While the tools are free, it still takes some time to master, as it is quite complex. It doesn't make sense for small organizations that don't have a big budget for this (as mentioned by others, MediaWiki can be quite successful in those cases). But if you want high-quality process documentation, and are willing to put the required effort into it, this is an amazing tool. To get an idea on how the results look like, check out OpenUP - it has been built with these tools. For organizations of a certain size, especially if they aspire ISO 9001 or CMMI certification, this is a good choice. The biggest disadvantage: It doesn't encourage collaboration.
Under capitalism man exploits man. Under communism it's the other way around.
Funny how this post has basically turned into an argument for efficiency and lay-offs, but in the real world, this is not really the case. Yeah sure, we can all envision the scene from 'The Office', when the Bobs come in and everyone looks worried, but in the real world, companies that truly have a grip on things tend to have good process documentation in place, and the major stakeholders in the business understand and support its needs and purpose.
Technology, in-and-of-itself isn't really a huge barrier. There are a ton of solutions like Wiki systems, Sharepoint, etc. Picking the actual technology to drive the system is - at least in my opinion - trivial. Lots of good FOSS solutions, and lots of good solutions otherwise. A good, properly maintained sharepoint system has the potential be be excellent.
It really is a matter of getting buy-in from all levels, and selling it to all employees. The wrong thing to do is have a big staff meeting in a common area and say "This is Bob. He's going to be doing some consulting for the HR department. He's going to help us see where we can tune things up.". You need to start right from the top, and work your way down. It's very easy to rationally sell the concept on employees, just as long as its explained clearly and properly. Communication is the key.
And communication has to be two-way. As another user pointed out, you can too easily make the mistake of implementing 'the-big-thick-binder-which-no-one-reads-and-is-not-kept-up-to-date-anyways' approach. Everyone understands and accepts that to a certain point, there must be process and documentation behind their positions. If they understand that, they can be a much greater help instead of a barrier. If there's a big worry that the process is going to 'more easily make people replacable', than you need to tackle that objection head on. Don't avoid it, address it and discuss it.
If everyone is on the same page to begin with, it will make the whole process actually happen, and happen (relatively) easily. Getting everyone on the same page might be 90% of the battle in some cases. That should be best practice #1.
Slashdot comments aside, I think most reasonable people understand that in order to organizations to function properly and efficiently, there needs to be a certain level of documentation and process behind everything that's done.
well. i work in a biggish company. IT, as usual in such places, doesn't believe they're part of the company. which is understandable, since the company actually spun IT off for some sort of financial benefit years ago. what goes around, gets what you pay for; it's now the domain of offshores and contract workers who have no idea what's going on with the business busily spinning off odd projects with limited and/or wrong documentation, and inability to answer questions. so: a visionary middle management type in my dept wants to set up a wiki to pool our knowledge base so we can do our jobs better. first step: IT has to run it. we're stillborn, but zombie on anyway. IT says: can't use mediawiki! it might explode or something. we need good, stable, tested software. sharepoint. oh boy. nobody on IT will admit to knowing anything about sharepoint, however. well, we're frigging geniuses, so we figure out how to more or less function. so, IT decides it needs to move the wiki to another server after a bunch of pages have been painfully constructed. Oh, did you want that content moved too? sigh, i suppose we could dig them out of the backup tapes.... we soldier on. next skirmish: we need to take down the server it's on (which we just moved it to) for a while. like, a few months. note that we're not getting paid for the effort needed to fight these battles. i've surrendered, myself.