How Do You Handle Your Enterprise Documentation?

An anonymous reader wonders: "I'm curious as to what tools Slashdot readers use to inventory and document their networks? What got me thinking about this is the part VMWare has been taking in data centers. You've got your SAN, various physical and logical networks, various VMs, and so forth. It just adds a new layer of complexity in terms of documentation. I'm curious as to what people have been using as for doing things like documenting how their backups work, LAN settings, FW settings, where and what runs what services, and so forth. How do you blueprint your entire IT infrastructure so that someone brand new could start and figure out what does what?"

Comments

Use a Wiki

[Silver Sloth]

The biggest problem with documenation is that we're all too busy keeping the systems running to write up what we did. It therefore is neccessary to use a system where

• It's easy to amend/update
• Access is controllable
• The content is searchable

All this screams Wiki to me. If you're capable of setting up the sort of VMWare system you describe then installing Wikimedia will be a piece of cake.

Re:Use a Wiki

[Silver Sloth]

The problem with insisting on full change management protocols is the same problem as with hyper tight security. If you make things too difficult then people will find ways round it.

For example, in the organisation I work for make a change involves a seven page document with a five working day lead time. On the other hand, changing configuration in response to a customer complaint can be done instantaneously with the minimum of paperwork. So, if you want to get something done, get a customer to raise a complaint to avoid the paperwork.

As such over complex systems are self defeating.

Media Wiki

[RingDev]

I'm working hard at convincing my management to impliment a Wikipedia style documentation system. I've demoed some of the possibilities and it looks like a great tool for it. So good that I've recently installed Media Wiki for another large company looking for a documentation system. For its ease of use, configurability, and built in functionality, it is truely a great tool.

Now if I can just convince the last supervisor that Media Wiki is better than MS Word with Track Changes turned on (shudder!).

-Rick

Re:Easy!

[richdun]

Sadly, I think that would win a poll of the average /.er and others.

Re:no, it's called job security....

[jofny]

Poor documentation only helps job security when it hides how truely haphazard your code/environment/IT system implementations actually are

Please please PLEASE have a docs specialist

[Anonymous Coward]

I'm a techie, I know how to program, manage networks, install & configure domain controllers, I can rattle off hundreds of Unix CLI tools
However, my writing for non-techies sucks.
Companies: once your IT departments hits about twenty people...you need to hire a technical writer or a documentation specialist.
When you get ten or fifteen geek-nerds contributing to one document (eg: "the disaster recovery scenario"), the document WILL be a mess

TDz.

Re:Documentation? Think of your job security!

[digitalhermit]

Oh no no no no...
You document, just don't document *completely*. E.g.:

1) Disable the old httpd server: rpm -e httpd
2) Rebuild the new server using the appropriate patches.

  This leaves you the right to say, "I documented the process." You look like a hero for taking the initiative in just doing some documentation, and also makes the bosses stay away. If someone takes you to task for lack of detail, insist that that particular process is obvious and look bewildered that someone wouldn't know how to do it. "What? Document a rebuild? Does that mean I need to tell them how to turn on the computer too?"

  Math teachers have been doing this for years:

I'll leave the details as an exercise for the reader.

Re:Uhh, the usuals?

[walt-sjc]

Organizing the 1000 or so word documents in any kind of reasonable fashion is a nightmare.

I much prefer a wiki.

Re:Easy!

[chris_mahan]

Same here...

My managers are like "What have you done lately?"

My reply: Documentation, stability and scalability enhancement

Their reply: "What for? Deliver something to the customer!"

My reply: "I have: zero downtime in the past 12 months."

But do they care? No.