How Do You Handle Your Enterprise Documentation? 125
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?"
Easy! (Score:3, Interesting)
LIVELINK BY OPENTEXT (Score:1, Interesting)
Confluence (Score:2, Interesting)
Trac (Score:3, Interesting)
Rate my network diagram! (Score:1, Interesting)
http://www.ratemynetworkdiagram.com/ [ratemynetworkdiagram.com]
Re:Use a Wiki (Score:3, Interesting)
Sadly, we don't have the time (like you said) to go out and find this stuff and determine the status.
Within the last couple of hours though, I've found Technical Support software (which we need badly), that will scan your network for all kinds of info. I won't list anything specific because we haven't gone with anything yet nor do I want to look like I'm advertising. But, these packages look pretty promising and some offer reporting ability.
Now, the bad part is, we want to create "God Books" for each one of our servers detailing EVERYTHING about it and how to bring it back from the dead, if needed. Talk about a pain in the ass. Although, I never thought of a Wiki. Since we want to stand one up anyway, that would be interesting. I'd be interested in seeing anything like this anyone has created.
Re:Use a Wiki (Score:3, Interesting)
In reality, the official process turns a 1 month project into a 2.5+ year project (already past year 2, end still not in sight). The 6+ month projects could never be done using the official methodology, so they're clandestine. The strict requirements have caused us to abandon all reason and good judgement and just do as little as possible across the board, resulting in insecure environments that are not administered with applications that are held together with duct tape. There's such a strong push for no single point of failure from an official company perspective that it results in many key people never having time to train anyone else, so major pieces of functionality and knowledge are lost everytime someone leaves. This creates an environment where people don't want to stay.
One of our DBA's set up TWiki to document things. It looks decent and seems like a good idea to me. It's probably noncompliant with company policy on many fronts, so it probably can't be the official repository here, even though it's many times better than what we do have. I like the idea of anyone being able to find the documentation and fix it as well as using version control to allow anyone to see past revisions in case someone's "fixes" are wrong.
That's way better than the methodology we use where all the documentation has to be watered down to the point where no useful or accurate information is presented, they admit that form over function is the rule for the entire process, and no one could ever find documentation for any project anyway, because there is no common place to put the useless powerpoints.
Re:Media Wiki (Score:3, Interesting)
Re:Easy! (Score:3, Interesting)
All the Win admins, who tell the CIO they don't need to pay me to do admin work when everything is working perfectly, and then worship my skills when something breaks, can figure it out themselves if I'm not around. I'm tired of babying them, and giving them detailed written instructions for stuff that they should damn well know how to do.
Document for Life (Score:4, Interesting)
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 document everything (Score:3, Interesting)
As far as the network itself is concerned, I'm in the process of physically visiting every pc and printer in our building, writing down its name and cable number then putting that information into a spreadsheet which also has what switch the equipment is on and what port, with each switch having its own tab. I also do updates to machines if people aren't at them.
CiscoWorks gives me the switch and port info so that is the easy part.
Before I left my previous job, I did a knowledge transfer for our SAN with the guy who would be dealing with it. I worked with him for two months so he understood how the physical connections worked, why they were connected to both sides of the SAN switch, the importance of keeping your cable numbers accurate, how to add devices to the SAN, creating LUNs, the whole works. He documented everything and expanded upon what I had already done, including screenshots, in a binder so (hopefully) anyone else who has to deal with it can follow the pictures. The best part was the physical layout of the SAN switch. All anyone had to do was have the printout, hold it up at arms length and they could see exactly what device was on what port and what adapter was on what side.
I also documented everything I did with printers so, as I told people, "When I get run over by cars who refuse to stop at the red light as I'm crossing the street, any idiot can pick up where I left off." Every printer, including model, IP, location, name, etc was kept in a spreadsheet as well. There were only 800 or so to deal with. I guess I could have memorized everything.
Sadly, I've found out that since I've left, things aren't anywhere near what they were when I was there so apparently the idiots that are still there can't follow simple directions.
So yes, documentation is critical. Everything, no matter how minute, must be written down, labeled, etc. I'm doing my best at this location to bring some of that mentality to bear but it's going to be a long and tedious process. Try doing a Visual Studio install on a machine and getting "Error code 103" or "The system cannot find _setup.dll which is necessary to complete the installation" without documentation on how to work around the messages. Of course, if the programmers who wrote the installation programs for Visual Studio would have known what they were doing, these messages wouldn't occur. But that's a different story.
Re:Easy! (Score:4, Interesting)
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.
Re:Uhh, the usuals? (Score:3, Interesting)
* If you're looking at something, and it's wrong, you can change it without missing a beat.
* There are no worries that you're using an old version of the documentation
* It's got a search engine
* All changes are versioned
* We have all passwords information encrypted
If you make documenting something simple, people will document it. If you make it hard, people will not.