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?"
... we don't.
Livelink by Open Text is simply the best solution on the market for ECM.
We use Confluence, a wiki from Atlassian. It also integrates well with Jira, their bug tracking program we also use. Both products are popular with some open source projects, the names of which elude me at the time.
Trac is what we use for network, backup and project-documentation. And bugtracking. And for browsing through our projects' code. "It just works (tm)".
This sig is intentionally left blank
make sure you are consistent with the industry...
http://www.ratemynetworkdiagram.com/
This is pretty scary because my org has been attempting to find the best way to document for the last week. With over 700 computers/servers/laptops, all seperated into regions up to 9 hours away, its a little painful. On top of that, we've noticed that the past admins haven't documented anything since 2000...
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.
It doesn't work. I work at a company that has strict requirements for following a defined process with a lot of documentation for every project. The official story is that we need to do all of this because we're a bank and SarbOx requires us to be thorough in our documentation of everything. That's +100 for creating a ton of jobs for people who perform no necessary function, but -infinity for good thinking or recognition of reality.
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.
At my company (a software company) we use Media Wiki for all internal documentation, including server and network configurations. It's working quite well. Having free-form documentation, rather than a strictly organized hierarchical model, means people are more inclined to toss in information as they think of it. For example, if I upgrade PHP on a server it takes only a few seconds to update it in the wiki. No time wasted looking through directories or document indexes.
Developers: We can use your help.
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 know I've written it in a previous post but when documenting a procedure, installing a piece of software for instance, my documentation starts with "Insert CD" and ends with "Remove CD". Every step along the way, every instance of clicking Yes/OK/No/Cancel/whatever, is documented.
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.
We will bankrupt ourselves in the vain search for absolute security. -- Dwight D. Eisenhower
[We're so not 'enterprise' anything] But I'll say that for our small show, switching IT documentation over to a Wiki has been amazing.
* 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.
# (/.);;
- : float -> float -> float =