Slashdot Mirror
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?"
Word+visio.
Of course the person creating the drawings and documents must be proficient in technical writing (aka not an idiot), because no matter what tools you have, if you don't know how to explain things, they'll be useless. Try to get your documentation peer reviewed to make sure it makes sense.
I tried organizing textfiles for all the chapters and gifs, but it's much easier to just fork over the money and pay for the printed version. Paper makes for easier reading and browsing, too, like with any other book.
c al-Manual/dp/0671704273
:)
Amazon has it for $25 here:
http://www.amazon.com/Star-Trek-Generation-Techni
Enjoy
- 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.init 11 - for when you need that edge.
Generally, you'll be hard pressed to get techs to document anything. Simple reason: If it was documented, anyone could find the junk again. Not just them.
It's our way of securing out jobs. If you want a CD or want to know what this button does, hell, ask. You can even call us at home, even in the middle of the night, we won't even get too mad if you throw us out of our cozy beds at 10am with a call, but don't ever dare to question our way of organising things. If you ask a tech where the documentation is, he'll tip his temple and say "here".
That way you can't fire him. In today's corporate world, it's an essential job security thing to NOT document. If you have to document it, write it down and then reshuffle everything.
Sorry to be not too helpful, but that's simply how it is. At least for me. And now excuse me, I need to hunt down that (censored) tech, I need an MS-Office CD.
We used to have a Bill of Rights. Now, with the rights gone, all we have left is the bill.
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
"Most people in the U.S. wouldn't know they live in a tyrannical state if it walked up and grabbed their junk." - MyFirs
Documentation is not a project you finish.
It's something you do as best you can in-between other stuff. (Preferably starting with the stuff you are working on already.)
Then, the next time you do that, just go back and open the document and update it as you go through.
In our small company, we use a scattering of web sites (SharePoint or FrontPage based), network folders, individual "not done yet" documents, and a (yick) Wiki. I would like for us to use "Public Folders" on our exchange server as it doesn't involve teaching staff members to do stuff they don't already know how to do. (Some folks are not technical enough to even handle a Wiki.)
You just keep at it, and over the years you get better stuff as a collective whole. Be sure to clean out the stuff that is no longer valid, (but maybe keep it archived).
EVERYBODY needs to be writing it. I figure for every full time difficult to learn job, there's about two full time documentation jobs. So don't worry if it doesn't ever get complete. It won't, and for the most part it doesn't HAVE TO.
Also, for everyone's sake, get a dual monitor setup so you can easily document while you work on the other screen. Since our staff got two or more monitors, documentation creation rates have skyrocketed.
Of course, if you are a regulated body or get audits, it's a really good idea to review all your requirements for that once in a while so you don't waste effort doing the documentation wrong.
I hate percentage goals. What a worthless metric. If I have a great year for programming (like I did last year), then the next year my job responsibilities double and my code output drops, did I become less productive...or more?
It's like taking a poorly written application and cleaning it up, so that when you're finished, it's smaller than it was when you started. I did that a couple of months ago and this dumbass kept overwriting my new code with the old code, because he assumed that the new code must be bigger than the old code, and couldn't be bothered to look at the timestamps.
ad logicam Claiming a proposition is false because it was presented as the conclusion of a fallacious argument.