Slashdot Mirror

← Back to Stories (view on slashdot.org)

How Do You Handle Your Enterprise Documentation?

Posted by Cliff on from the describing-your-infrastructure dept.

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?"

29 of 125 comments (clear)

  1. Easy! by locokamil · · Score: 2, Interesting

    ... we don't.

    1. Re:Easy! by richdun · · Score: 2, Insightful

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

    2. Re:Easy! by SatanicPuppy · · Score: 2, Interesting

      I'm a coder and a unix admin...Unfortunately, I don't get paid to be a Unix admin (as the CFO told me, right before she cut out my raise), so while my code is documented to death, my network architecture is cryptic and erratic. Some services are enabled as I use them, but not set up to enable on boot. Some machines are in oddball locations in the building, and they're all headless, and unlabeled. Since the network infrastructure of the building is crap, I've had to pull my own cable to some machines to get adequate bandwidth, and that means that servers aren't necessarily plugged in where you'd think they would be.

      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.

      --
      ad logicam Claiming a proposition is false because it was presented as the conclusion of a fallacious argument.
    3. Re:Easy! by chris_mahan · · Score: 2, Funny

      While I completely agree with you, I now know why your nick is SatanicPuppy. Winy yet Evil.

      --

      "Piter, too, is dead."

    4. Re:Easy! by chris_mahan · · Score: 2, Insightful

      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.

      --

      "Piter, too, is dead."

    5. Re:Easy! by chris_mahan · · Score: 2, Funny

      Oh, as an aside, my boss said he had a problem. For our goals, he has to reduce the number of tickets filed against our applications by 40% next year, in order to meet his achievements benchmark. The problem? We only had 1 ticket filed last year against our applications.

      --

      "Piter, too, is dead."

    6. Re:Easy! by SatanicPuppy · · Score: 3, Interesting

      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.
  2. Uhh, the usuals? by toleraen · · Score: 4, Informative

    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.

    1. Re:Uhh, the usuals? by walt-sjc · · Score: 2, Insightful

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

      I much prefer a wiki.

    2. Re:Uhh, the usuals? by PylonHead · · Score: 2, Interesting

      [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 =
  3. Just order it from amazon by T.Hobbes · · Score: 4, Funny

    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.

    Amazon has it for $25 here:
    http://www.amazon.com/Star-Trek-Generation-Technic al-Manual/dp/0671704273

    Enjoy :)

  4. Scuse me? by justkarl · · Score: 2, Funny

    ....What documentation?

  5. Use a Wiki by Silver+Sloth · · Score: 5, Insightful
    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.
    --
    init 11 - for when you need that edge.
    1. Re:Use a Wiki by WebCrapper · · Score: 2, Interesting

      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.

    2. Re:Use a Wiki by Silver+Sloth · · Score: 2, Insightful
      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.

      --
      init 11 - for when you need that edge.
    3. Re:Use a Wiki by qwijibo · · Score: 2, Interesting

      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.

  6. Documentation? Think of your job security! by Opportunist · · Score: 3, Funny

    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.
    1. Re:Documentation? Think of your job security! by digitalhermit · · Score: 2, Insightful

      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.

  7. Media Wiki by RingDev · · Score: 4, Insightful

    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
    1. Re:Media Wiki by truthsearch · · Score: 2, Interesting

      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.
    2. Re:Media Wiki by Degrees · · Score: 2, Informative
      At least with older MediaWiki (ver. 1.4), it didn't search on IP addresses. That is to say, each octet of an IP address was too small for MySQL to index, so you couldn't search by IP address. If you knew you were looking for the Central Plant router, you were fine - but if you had 192.168.2.123 and wanted to find where that was used, you were s.o.l.

      Another deficiency is that MediaWiki doesn't support image map. Sometimes the best way to find info is to click on the picture....

      --
      "The most sensible request of government we make is not, "Do something!" But "Quit it!"
  8. Confluence by sof_boy · · Score: 2, Interesting

    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.

  9. Trac by AlXtreme · · Score: 2, Interesting

    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
  10. Re:no, it's called job security.... by jofny · · Score: 2, Insightful

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

  11. Please please PLEASE have a docs specialist by Anonymous Coward · · Score: 2, Insightful

    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.

  12. Document for Life by jafiwam · · Score: 3, Interesting

    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.

  13. I document everything by smooth+wombat · · Score: 2, Interesting

    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
  14. Re:no, it's called job security.... by camperdave · · Score: 2, Funny

    If you're irreplaceable, you get promoted by declaration:

    Power goes out in the building...

    "Hey! You know Larry, the pimply faced kid who fixes the computer stuff? Well, there's a new sign on his door that says 'Network Administrator', and he's got a parking spot now.".

    Larry goes on vacation, comes back...

    "Hey, Remember Larry, the network administrator. Yeah, he's now 'Director of Information Technology', whatever that means. Yeah, corner office and everything."

    Team of Efficiency experts brought in to improve work flow...

    "Hey, did you hear? Larry got canned. No, not that Larry, the computer Larry. Turns out he was, how did they say it, 'holding the corporate infrastructure hostage'. The boss said my idea about getting those consultants in will save them big bucks. Guess who has the corner office now, baby!"

    --
    When our name is on the back of your car, we're behind you all the way!
  15. We use 80-20 document manager by gtoomey · · Score: 2, Informative

    http://www.80-20.com/products/document_records_man agement.asp Its very much enterprise level. The inane comments here make my wonder if any of you have a job at all.