Catch up on stories from the past week (and beyond) at the Slashdot story archive

 


Forgot your password?
Close
typodupeerror
×
Businesses Communications IT

Ask Slashdot: Documenting Scattered Sites and Systems? 114

Posted by timothy from the you'll-need-a-lot-of-gasoline-but-only-1-match dept.
First time accepted submitter capriguy84 writes "Six months ago I joined a small firm(~30) where I am pretty much the IT systems guy. I was immediately asked to work on couple of projects without much going through the documentation on what currently exists. So I created new wiki topics everywhere and whenever needed. I am now in a situation where information is scattered across multiple pages and there is lot of overlapping. So I have decided to start a project of re-organizing the wiki so that it makes sense to me and easily accessible for others. I am dealing with 2 disjoint sites, 4 data centers, managing all flavors of Unix, windows, networking, storage, VMware etc. Along with that I have HOWTO guides, cheatsheets, contracts, licensing, projects, proposals and other things that typically exist in a enterprise. Any tips with how to approach? Dos & Don'ts? Recommended reading?"
This discussion has been archived. No new comments can be posted.

Ask Slashdot: Documenting Scattered Sites and Systems? More

Ask Slashdot: Documenting Scattered Sites and Systems?

Comments Filter:
  • I'd pick the right tool for the job. Go with some piece of software that's able to document your physical hardware and the software on it. Ideally, you'd find one that is able to discover on its' own what's there and continuously monitor it. It's a shameless plug, but one of the guys in my city has a product - http://www.pathwaysystems.com/ [pathwaysystems.com] Beyond kicking the pants off of a wiki visually, it is able to keep itself up to date. Use the wiki for the other documentation - the about's, how-to's, and cheatsheet

  • Target users and tasks, not systems (Score:5, Insightful)

    by wanderfowl ( 2534492 ) on Sunday January 08, 2012 @01:43PM (#38630444)
    Doing all the documentation for a few small IT projects, I've found that I'm better served creating task-based and user-based documentation than holistic documentation of the system. If you've a limited amount of time, I suspect it will be better spent creating easy-to-use guidelines for the most common interactions with the tech you're working with that people other than you will have. Step by step, idiot resistant, and with the technical nitty gritty just deep enough under the surface that somebody who understands, will, and that end users won't be troubled by it. It's a wonderful thing to imagine documenting all of it in some detailed, top-down and holistic way, but chances are that you (or whoever they replace you with) will be the only one looking at those guidelines, and that nobody will appreciate all that work, compared to a set of PDFs allowing anybody in the company with authorization to do X, Y or Z which make you look both useful and benevolent.
  • Youre in over your head, a one man army dealing with all the technology you listed is going to result in a mess for you and your employer. Get someone in there to sort it out and document it, then you should be able to manage it on a daily basis.

  • usage defines semantics (Score:2, Interesting)

    by Anonymous Coward

    Most used stuff on top, however you see it. (or the user community). Extremely vague advice, but just something to help keep rational.

  • Pretend you're the CIO not the IT guy (Score:5, Insightful)

    by vlm ( 69642 ) on Sunday January 08, 2012 @01:55PM (#38630536)

    Having worked in small environments I suggest pretending you're the CIO not just a low level IT drone.

    Create your imaginary virtual employees and organize your data appropriately.

    Unless you have a really good reason to go project based at the top level, I'm guessing as "CIO" your employees would be mgr operations, mgr development, mgr security/auditing who basically watches the other two or something like that. Take a wild guess what your top three level directories or top level three wiki pages I'm suggesting.

    It become an interesting role playing game, sorta. So, if we were big enough to have a guy who did nothing but R+S CCNP/CCIE type stuff, he would probably report to the operations mgr, so R+S type stuff has a wiki page linked from the operations page. If you had an admin/intern of license collation and recording working for the operations mgr, that would probably link off the operations wiki page, etc.

    This is also hyper convenient if the boss graciously grants you a summer intern, you can almost instantly trivially drop that person right into your pre-existing "system". Look kid, you're now officially an instant licensing admin, or whatever.

    Also in your summary of "stuff" you overlooked written EULAs you provide to your internal customers, request forms to fill out, whatever ticketing system you use, whatever project management system you use... And it seems helpful to have a public or private or whatever wiki or something documenting what metrics, if any, you provide to your boss for review time.

    • This is also hyper convenient if the boss graciously grants you a summer intern.

      Or if you are already the intern, without pay, you should consider quitting while you're ahead.

      • This is also hyper convenient if the boss graciously grants you a summer intern.

        Or if you are already the intern, without pay, you should consider quitting while you're ahead.

        Or if you are already the intern, without pay, you should document it and demand your pay. Most places, it's illegal to work as an unpaid intern if your work actually has any value to the company.

        • This is also hyper convenient if the boss graciously grants you a summer intern.

          Or if you are already the intern, without pay, you should consider quitting while you're ahead.

          Or if you are already the intern, without pay, you should document it and demand your pay. Most places, it's illegal to work as an unpaid intern if your work actually has any value to the company.

          Or you should get a paying job, since the company could care less what's illegal and is never fined.

    • To expound on this idea, the best thing to do is create an org chart that you can fill in of there are consultant brought in. Classically, you will wan to pull together these disjointed sites with a single LDAP directory (eventually if not now maybe later). These directories should mimic your org chart and locations to some logical degree. Your directory structure should mimic this LDAP dir as well. This can help you create role based security, deploy/manage applications, and organize security accordingly.

      • Re: (Score:2)

        by vlm ( 69642 )

        To expound on Dharkfiber another situation where an "imaginary org chart" comes in handy is creating logical demarc points/workflows for contractors. Formally in writing you already expect someone in a "cable puller" role to document new cabling as such, with a demarc point between him and the imaginary R+S LAN guy who configures the ethernet switches. Or perhaps you have a huge project and contract both roles out, this imaginary org chart shows how you get those two to optimistically work together.

  • Don't bother. Nobody will read it anyway.

    • Re:Don't bother (Score:5, Insightful)

      by BasilBrush ( 643681 ) on Sunday January 08, 2012 @02:15PM (#38630628)

      Agreed, don't bother. In a small company situation, it's good to be irreplaceable.

      • Comment removed (Score:4, Interesting)

        by account_deleted ( 4530225 ) on Sunday January 08, 2012 @02:26PM (#38630698)
        Comment removed based on user account deletion

        • Re: (Score:1)

          by Anonymous Coward
          If you're the one-man 'IT department' in a small company, you can't be promoted anyway.

      • Don't be perceived as a high school kid (Score:5, Insightful)

        by Zero__Kelvin ( 151819 ) on Sunday January 08, 2012 @02:34PM (#38630758) Homepage

        " In a small company situation, it's good to be irreplaceable."

        In a small company that doesn't have a CTO position, and thinks all of that technology isn't very complicated and can be managed by a single guy acting as "pretty much the IT guy" you are already (falsely) perceived as interchangeably replaceable. I remember one particular interview where I met with the CEO to interview and he wanted to low-ball my already quite low suggested salary. He told me that a high school kid could do what he needed. I simply replied: Well then you need to get yourself a high school kid."

        I recommend that you start focusing some effort on changing the false perceptions of upper management, because if they don't understand what is involved and why it is important, all your effort will go unappreciated and even the best solution will fall by the wayside the moment they need to save money to buy more staples.

      • There's no career ladder in a small company anyway. The way to progress in the same company is get good pay rises. And the more irreplaceable you seem, the more you can negotiate for yourself.

        • Re: (Score:2)

          by 1s44c ( 552956 )

          There's no career ladder in a small company anyway.

          There is no career ladder anywhere except that which you make yourself. The fat, balding, overpaid PHB will lie about such a thing existing though. Don't believe that guy.

          In a small company it goes:

          1) Fix, document, make it all work
          2) Use your good reference to get a new job with better pay

          Most people want to skip the vital first step.

          • "in" a small company. Of course there's a career path outside it. But documenting the company's IT system is not a vital step before moving on.

            Leaving a list of passwords for your successor is an obligation. Plus whatever it is they ask you to do during your normal working hours during your notice period. Which may or may not be documentation.

            • Re: (Score:2)

              by 1s44c ( 552956 )

              Doing a good job is a vital step. If you don't do that you don't deserve to progress.

              Companies want people that do a good job, not people that do as little as they can get away with.

              • On most occasions the only link between the old company and the new is a reference. And they're not worth the paper they're written on. For the most part they are boilerplate. And if they're not, they can be good because an old employer is glad to see the person go and vice versa.

                For sure being a terrible employee can be a problem. But the difference between doing what you were asked for and doing something extra won't make a scrap of difference to future employment possibilities. Not at the "IT guy for a

    • More usefully: write this shit up for yourself. Point your boss at it to show you're on top of stuff, but write the doc you would want to read, and so you know what the hell you did six months ago. This is what I do on our intranet wiki. I then point other people at it 'cos that's where the info actually lives, but as far as I'm concerned it's my online notepad.

      • This. (Score:1)

        by Anonymous Coward

        Exactly.

        Especially if you're in a one-man systems position. You write for yourself. You write for the IT department or systems team that doesn't exist. You don't write for Bob in Accounting.

        The next guy to come along will either:

        1. Understand it
        2. Not understand it because he sucks
        3. Not understand it because you suck

        Obviously, #1 is the best scenario. #2? Not your problem, and the company will learn a valuable lesson by hiring the guy replacing you.

        #3? The company will also learn a valuable lesson

  • consider the use cases (Score:5, Informative)

    by lophophore ( 4087 ) on Sunday January 08, 2012 @02:01PM (#38630558) Homepage

    Consider who will be using the information, why, and when.

    Determine the most common use cases for the information you have collected. Then organize the information to suit.

    Server died. What do I do?

    Add a user: What do I do?

    etc. Think about where you will be in a year, and how this information will be used when you have forgotten most of it, or in panic firefight mode, or gone on to another job.

  • Semantic Wiki (Score:5, Interesting)

    by sperxios10 ( 848382 ) on Sunday January 08, 2012 @02:10PM (#38630596) Homepage

    Last year i used MediaWiki's SemanticWiki [semantic-mediawiki.org] to describe the systems, projects, human-resources, external-urls and their dependencies of a telecom.

    Besides trivial parent-child relations among developers/employees, departments, etc,
    i described system dependencies as semantic-relationsships with names like this: part of, invokes, build by, implements, deployed on, etc.

    I described developer responsibilities with names like this: maintained by, coded by, external contact, etc.

    Finally, the documentation pages and the refs to external-URLs of projects were reorganized by semantic-relations, like this: javadoc, docUrl, webApp, section of, help page, etc.

    • With relationships like these, you can present different generic views into the same page set. One point I'd add is that it's useful to have, as the primary hierarchical structuring of the data, a fairly accurate reflection of the way the business itself is organized.

      After all, computing infrastructure is essentially a model of the business, plus additional technical constraints. There should be a strong isomorphism between the two. If your documentation reveals this, not only can everyone navigate th

      • Actually nobody likes to be reminded of the hierarchy above him or her. And most of the times the official hierarchy-diagram does not denote the complete command-and-control relations. Therefore, i skipped the political part of the "fairly accurate reflection of the way the business itself is organized" and concentrated on the technical aspects of the business, some of which i described above. Assuming that all technical data were complete, you could grasp the way the busines is organised by running queri

    • Plus automatic inventory system.

      Seriously. Wikis are horrific databases. Once the information is in there making use of it is a nightmare.
       

      • SemanticMediaWiki(SMW) can utilize triple-stores [semantic-mediawiki.org] (proper RDF databases). But even without using one you can make still run queries from within wiki. You create the new query by using a special query-page and after you are satisfied with it, you embed it in any wiki-page. Next, whenever you view this page, the semantic-results come always fresh on that page. Compared to a RelationDB, SMW comes bundled with UI. You just have to learn a new syntax for running the queries.

        Now to get the results in differ

        • Re: (Score:2)

          by csirac ( 574795 )

          +1. We use Foswiki, with its DataForms for consistently structured data, SemanticLinksPlugin for ad-hoc relationships (though relationships themselves are also managed, sometimes with more SMW-style links), JQGridPlugin, MongoDBPlugin to ensure our poor VM can keep query speeds up regardless of how many pages we get, DirectedGraphPlugin (graphviz) for simple network visualisations and an http://thejit.org/ [thejit.org] based interactive js visualisation to explore our entirely wiki-based datasets, along with an experime

  • We had a collection of random documents for one of our sites that needed to be organized and gathered up and have duplicate information eliminated. I considered a Wiki, but my boss wanted it in more of a book format so we could keep a hardcopy on hand, so I chose a massive Word 2010 document built from scratch with all the appropriate tables of contents, sub-indices, and a keyword based index for rapid searching near the end. Since this "from the ground up" book needed to be written and edited by one pers
    • If you want to write a book, consider using Lyx (Link: http://www.lyx.org/Features [lyx.org]) instead of Word 2010. It keeps track of all indexes, links, references, footnotes and TOCs, produces PDF output with links to everything you desire to cross-reference, and gives you a printed output much better than any version of Word. Give it a try!

    • Re: (Score:2)

      by CAIMLAS ( 41445 )

      Wow, seriously?

      You do realize that there are half a dozen different 'bookify' extensions/plugins for MediaWiki, right?

      Consider a scenario where you've got multiple contributors working on updating it at the same time, or where you need a content/section specific change control audit. The change control, etc. in Word is not capable of this granularity.

  • This is Strategic Architecture (Score:5, Interesting)

    by rhadc ( 14182 ) on Sunday January 08, 2012 @02:15PM (#38630632) Journal

    Capriguy84,
        Over the last few years, I have worked with a service provider on what to an outsider would sound very similar. The organization's processes, applications, and information had been distributed throughout the company on an ad hoc and project basis, resulting in an irrational de facto architecture that contributed inefficiency to practically every activity. For any organization, addressing these systemic issues will always be a work in progress. Although my case differs in scale by more than a factor of 100, I think the lessons I've taken may apply for you as well.

    1 - Dysfunction is not a product of the technical situation. It is a product of management. Thus, it can only be addressed by management. For you, this means you have the opportunity to lead the organization to the right outcome, and you will have to get management support to get folks to change their processes. It looks like this: a) Identify the outcomes the org is looking for. Not "FAQs on the same server," but "Knowledge Management - Processes and technology to get and KEEP key company information accessible when necessary and secure." b) Obtain management support on the outcome. c) Explain the steps and costs needed - technical and non-technical. Management must ensure that new knowledge lands in the right place and people to go to the right place for the info. d) Implement - the technology and the culture changes e) Evaluate.

    2 - What you are doing is not unique to your organization. Practically every firm has this problem in varying degrees. Go scan through the book "Faster Cheaper Better" by Michael Hammer to see an articulation of the issue at a very high level - not specific to knowledge management.

    3 - There are frameworks that help guide the architecture process. Have a look at TOGAF. These are model driven, and frankly, they are very hard to consume and live by. Nevertheless, the point of these is roughly the same. When the problem is too large, divide and conquer. Model the organization and subject matter by dividing it into its parts. Prioritize, strategize, etc. Having the model enables you to ensure that solutions at the micro level are in harmony with those at the macro, etc. TM Forum does this for telecoms.

    4 - Since the most important part of the job is getting buy in from management and those having to live through the culture change, your soft skills are more important than the tech skills.

    All this might look like killing an ant with a sledgehammer. I suggest that you take a little time glance through material on how this is done at large scale and apply whatever seems pertinent.

    Good luck!

  • Start tracking what you are doing (helping users, babysitting machines, provisioning, upgrading, debugging, etc.) Then track time wasted by your co-workers, users, etc. Then track hardware costs, licensing costs, etc.

    Estimate dollars/year for the stuff you can see/could improve. Focus on the high cost stuff: ask the users of that stuff if they would prefer you to take ownership and get the cost down, or if they would prefer to just manage the stuff themselves.

    Then start fixing the stuff they would prefer yo

  • google for 'itil' (Score:5, Insightful)

    by Bazman ( 4849 ) on Sunday January 08, 2012 @02:19PM (#38630654) Journal

    Do you know what ITIL is? Find out. Then get yourself a CMDB. There's open source ones so you're not going to break the budget.

    http://www.cmdbuild.org/en/index_html?set_language=en&cl=en

      Then get yourself a document management system. Alfresco? It's a monster.

    If you can tame those systems, then you can look for a massively well-paid job with a bigger company that wants to leverage enhanced ITIL capabilities in an enterprise solution situation scenario. F**k yeah.

    • Re: (Score:2)

      by RMH101 ( 636144 )
      Seriously. Do this. If you don't want to, get someone hired to do this. If you have existing enterprise support with a big vendor like HP or MS then they can do this for you if you're willing to pay through the nose for it.

  • This is an active area of research, scholarship and discussion. There probably isn't one right answer or even a simple answer. I have a friend who just got her PhD in Information Science. She was tackling a similar knowledge management problem. The only people that seem to have made much progress on this are reference librarians. Is there a reference librarian out there who would like to comment?

  • If you don't know what I meant by linchpin, read Seth Godin's book.

    In my IT times, there was a day that I was finger pointed (for the Nth time) of not providing enough training for new comers. (Me, the sole IT for a 30 people office).
    I setup an internal server with moodle (the learning platform),
    created a whole course in everything IT for the company, and of course, <buhaha>exams</buhaha>.

    The failure rates and the time to pass were [un?]surprisingly high.
    Due to the revolution I had let it be mor
  • You can spend a lot of time trying to come up with a structure that makes sense, for the data you have now. I doubt you will succeed considering the variety of data and users you have to serve, and it will only waste time.

    Even if you came up with something that will work fine today, it will require a lot of maintenance and probably have to be changed regularly to keep up with the new type of data you will need tomorrow.

    I have had to deal with such problems under different environments, and what I found

  • Have you considered hiring a Technical Writer on contract?
    From the work you describe, someone with the right experience should be able to pull all of that together for you in about a month -- maybe a bit longer to make sure that it's usable for you in the long term. Writers spend a lot their time summarizing, re-organizing, and pulling together disjointed pieces of information. I'd consider hiring someone to get you running, and then having them show you a few things for how to keep the wheels greased in th

  • inventory managment (Score:3)

    by slashmojo ( 818930 ) on Sunday January 08, 2012 @03:30PM (#38631182)

    You may also find an inventory or asset management system useful to make sense of what you have, if its relevant in your circumstances. There is web based or software like http://www.ocsinventory-ng.org/ [ocsinventory-ng.org] http://www.tracmor.com/ [tracmor.com] http://www.pukkapanel.com/ [pukkapanel.com] and others mentioned here.. http://www.cyberciti.biz/tips/open-source-it-inventory-control-systems.html [cyberciti.biz] or if you use RT there is http://requesttracker.wikia.com/wiki/AssetTracker [wikia.com]

    There's also a previous /. discussion on asset tracking stuff although perhaps a bit outdated now.. http://slashdot.org/story/06/08/20/0214256/it-asset-tracking-and-helpdesk-software [slashdot.org]

    • Re: (Score:1)

      by simpsop ( 413073 )
      Freeware OpenAudIT works well too for a systems discovery / inventory tool. Runs great on a small linux box with php, mysql, apache. Interface to nmap, can collect all hardware, OS, Network info, as well as installed software and patches. Base setup took me about 15 minutes.

  • I have a similar setup (less locations, but the same sort of cluster foxtrot of non-documentation) and I use a wiki. I'm not sure what you're using, but I used MediaWiki. I created a name space for "servers" (actually VM's) and document their function, specs and what hardware (as a link) they are on. Now I can go to any hardware page and click "what links here" and see all the VM's on it. Of course that isn't perfect because there can be other links to the hardware, etc. I'm going to be trying out Semantic Mediawiki next because it'll let me query better (What servers are under X ip address, or Y location).

    It's not a perfect system, but it works for me. I like working with MediaWiki and know it fairly well. It also allows me to keep other documentation with it that, yes, sometimes just tossed in there but at least I have search. I've tried some specialized "rack inventory" software but I haven't been terribly enthused by any of them.

  • Sharepoint (Score:1)

    by Anonymous Coward
    You should probably just install Microsoft Sharepoint and move all of your documentation, etc. into that. It provides facilities for everything that you are asking for and is easy to get management buy in since so many shops use it and you probably already have servers available to run it.

  • BTDT (Score:2)

    by CAIMLAS ( 41445 )

    I've BTDT. There are a couple solutions, all of which depend on the time you've got to throw at the situation. The basic problem is "how do I keep track of all my configuration, process, and environment documentation in one easily accessed place, and how do I keep it consistent with the environment?"

    I looked at using Semantic Wiki, but I never ended up using it (can't recall why, exactly - it may have been due to not having the ability to use the full suite of MediaWiki extensions). If there's a way to migr

  • Don't do it at all, unless you've been told to (Score:3)

    by melted ( 227442 ) on Sunday January 08, 2012 @05:39PM (#38632048) Homepage

    Unless you've been told to do it, don't do any of this at all, for two reasons:
    1. Documentation efforts are often perceived by management as a waste of time
    2. By documenting everything extremely well, you create a visibility that it would be easy to find a replacement for you if you e.g. demand a raise or screw up one day.

    Cynical, I know, but in most places, those are the rules of the game.

    • Re: (Score:2, Insightful)

      by Anonymous Coward

      This diverges from the main topic of this thread but I wanted to respond to #2 above. When acting in either support or developer roles I create and publish useful documentation in an incremental fashion for my own benefit and for my peers/replacement. Some believe that this makes me dispensable. My view is that it frees me to spend my time doing more important things for the company, improves management's perception of my capabilities (when I'm able to fix things quickly this looks good), and frees me to ac

      • Re: (Score:2)

        by melted ( 227442 )

        >> I've got a project that we think you'd really be able to help

        And that, my friend, is when you document stuff, by gathering your notes and throwing them up on the Wiki. But in a small company, I don't see how this situation would ever arise. And in a large company, unless you actually demand that the project be assigned to you, you won't get shit, because someone else will be assigned to it instead. I've seen many an engineer wither and burn out by waiting until they're _given_ more responsibility.

    • Re: (Score:2)

      by PPH ( 736903 )

      No. Do it. The visibility could earn you the proper visibility you'll need to get the resources to do your job. If you can't show management the scope of the problem, you'll never get proper funding to support it.

      Back in a previous job, our IT department was angling to take over responsibility for one of our (engineering) systems. Management commanded the production of complete documentation of our systems in order to bring my replacement up to speed. One component of the documentation was a one sheet over

  • All I can give is the benefit of being in similar situations myself.

    My first point of call has been to think about the systems you are working on and work out the commonalities. From there I've start to standardise them into documented systems that are version controlled - your wiki is a fine start to this but I've previously found the same issues you have - fragmentation based on the amount of documentation. This approach doesn't prevent you having lots of differences but does help you to keep track o

  • It is called hyper links....
    Build an annotated page of links
    same as you would a bibliography.
    heck -- word knows how to make such
    stuff purdy.

    Note that pdf files can have links (URL)
    that let you write an internal document
    that can reference this that and whatever.

  • search (Score:1)

    by Anonymous Coward

    When you need multiple ways to access data, a good "search function" may be the best way to do it.

    • Similar situation here, with tons of documents (Word, Excel, PDF, etc) scattered everywhere, along with project specific personal web pages on users stations, etc...
      I've set up a portal for our intranet and a project management system, but so far the most useful tool is an indexer (Xapian) and a search page (à la Google, available on the portal) since it allows easy recovery of "archived" (read "lost") older documents...

      The most difficult task is to convince some colleagues reluctant to changes that it

  • In my situation I used visio diagrammes in jpg with a client side image map. This did multiple things simultaneously: grouping and hierarchy. Geolocation and service clusters. Plus the CFIO could even drill down for her research! All the while retaining the full text search, etc., that the wiki provides. Good luck!

  • ITIL CM and Confluence and Patterns (Score:1)

    by Anonymous Coward

    Huge task you have there. Good luck.

    Can I suggest the following:

    1) Organise ITIL V3 Foundation training and start reading up on ITIL in general.
    It can help you organise your work environment into manageable areas - service delivery, service support, etc.

    2) Implement a CMDB
    Even if you only start with an Excel spreadsheet, know what you have.
    Good CMDB tools can auto-detect your network, create and update CI's.
    Even a basic CMDB which has a web interface and for which data can easily be uploaded and extracted f

  • Disclosure: I work for a small company that provides Systems Administration for other small companies.

    There are products like Labtech that allow you to install a management program on every computer, and then the management program reports back to the server with each system's details: Serial number, make, model, software installed, hardware installed, and much more. When we get to a new site, we install the management tool on a server, push it out to each device with a logon script, and pretty quickly h

  • Too many topics (Score:3)

    by ljw1004 ( 764174 ) on Monday January 09, 2012 @01:23AM (#38634922)

    "I created new wiki topics everywhere"

    I think that's the problem. Wikis are awful for gathering together information. Every individual page is too isolated. No reader can get an episcope, an overview of how all the topics fit together. Sometimes people suggest "make another topic that shows how the topics fit together" but this adds to the problem rather than solving it.

    You see the same problem with things like Javadoc which are great for creating lots of tiny little informations but bad for conveying the overview of how things fit together.

    The solution? Write FEWER topics, long ones. That way people can scroll through to get an idea. The brain's really good at skimming through large documents, understanding what the domain is, drilling down where it's needed. That's why books are so successful!

  • I keep seeing train-wrecks of wikis. Especially first hand, with one I set up. Wikis work so well with online communities and with Wikipedia because of the mindset of it's users and editors. You will not find this collaborative, initiative-taking, creative, mindset among your initiative-free cubical farm.

    Wikis really shine as a knowledge base when you have a group of people using as a collaborative tool to keep shit documented. Relying on one for your own documentation however is a special form of self t
  • I use Microsoft OneNote for this.. handles the job very well. You could also try looking at mind-mapping software like MindJet MindManager, or even freemind (http://freemind.sourceforge.net/wiki/index.php/Download) if that's more your style. But imho, MS OneNote is hands down the best for solving and maintaining this problem in the business environment.
  • I would suggest a document management system, with maps and floor plans, incident tracking, etc. to accomplish what you are talking about. (Disclaimer: I work for a company called Lauren Innovations that provides such a service, called NaviGate.)

    The system basically allows you to tie meatspace, with maps and floorplans, to your server documentation. All documentation can be deduplicated, by connecting similar documents to multiple servers. And finally, you can track all incidents related to the server

  • Keep it simple, keep it safe. (Score:3)

    by son_of_asdf ( 598521 ) on Monday January 09, 2012 @09:27AM (#38636594)

    PRIME DIRECTIVE: Regarding some of the above posts, If you are having to strategically "leave gaps" or otherwise write bad documentation for the purposes of monkey wrenching your replacement or making yourself indispensable, you suck to the 10th power. I have dealt with this sort of fuckery more times than I can count over the years, and every time I clearly see the signs of a small mind at work. Don't be that guy.

    I've have to do this routine a gazillion times in my role as an small/midsize biz consultant. Here's the formula as I see it:

    Find the keys to the kingdom, and document these. Don't worry about getting to the nitty-gritty yet: just find the info that will let you find everything else. Be extra careful to track down any crypto-related stuff (keys, passphrases) that can't be replaced or cracked. The further the old IT person recedes into the past, the harder this crap is to track down. Identify the scariest bits of the network as quickly as you can after you get hired and trumpet to the hills about how fragile, dangerous, and not your fault they are :-) Document all of this in plain-old-textfiles or something stupid simple, with bonus points if you keep it in version control.

    Set up some bug-tracking/ticketing software and use that to track all of your day-to-day documentation and troubleshooting. Redmine is my personal favorite, but RT and Trac are also good choices. They have simple, built-in wikis that are perfectly sufficient for this purpose. Use the time-tracking and project management features in the software: when the boss asks you where all of your time is going, you run a report and show him. Track every minute of your day: this time is excellent leverage for you when dealing with management.

    Examine the backups of the system (or implement them, worse) from ground zero. Use the backup audit as the trail of breadcrumbs that your documentation follows.

    Beg, borrow, or steal a chunk of hardware that you can stick Xen/HyperV/VmWare/AcmeHypervisor on and start test restoring various systems/apps/environments. Document the hell out of the test restore process. That's the most precious documentation that you can possibly have.

    Don't document things that document themselves. You're much better off paying $299 for a copy of LanSweeper or the like to reach out across your networks and document all of the mundane details in real-time so that you can focus on making shit work right. I've seen a million cases where the IT guy spent a month making a beautiful set of Visio network maps that became useless a month after they were created. That's a waste of your otherwise precious time.

    Now, start making recommendations about how to fix the fragile/scary/dangerous systems. Use your ticketing/project management app to track your recommendations and leave a paper trail of your process. There will be a fair amount of CYA involved here - you're going to recommend that the boss spend a bunch of money on $x, so you had better document the reasons for it with care.

    Whenever you make a recommendation that the company buy product $x to resolve problem $y, document it very very clearly in your system, and if the bosses nix your recommendation, document that in writing too. Yes, more CYA, but as the IT guy you're often the staked goat when something goes wrong. You need to be able to PROVE that you had recommended a sane course of action.

    Last: Try not to stress. IT is fun if you do it right.

    • Re: (Score:3)

      by pnutjam ( 523990 )
      Good point about obsolete documentation, the only thing worse then no documentation is incorrect documentation.
  • A lot of this advice is very good, including generating documentation form configuration. However, please be careful and secure the website where this information is posted, because it will contain enough information to allow hackers to really hurt you if they choose to try to attack your system

    • mod parent +1 essential. It is awfully easy to set up a painfully insecure documentation system, and rather more difficult to do correctly.

  • First, read the PSNA [everythingsysadmin.com] if you haven't already, it features good ideas on documentation and especially process and how to deal with "layer 8" (management, users, whatever is the "real world" for you).

    Next step is the wiki. You seem to already have that, good. People here have suggested SemanticWiki [semantic-mediawiki.org], but I'll point you towards Ikiwiki [ikiwiki.info] as it has the advantage of (a) being git based so completely decentralised (have a copy of your files on your laptop during a downtime!) and (b) written in perl so you can probabl

  • If you ike the wiki solution keep at it. I find wiki to be a bit cumbersome, and would likely do some form of template toolkit plus markdown or pandoc. However if you need reversion or comparison to previous forms of documentation, then wiki may be the way to go.

    What I would suggest doing, is to budget a time slot each day for system documentation.

    Step one: Consolidate into a single system.

    Step two: Look at your work for the day before. Based on that spend an hour working on that chunk of the document

  • This is where Google Wave would have shined. That Google pulled the plug on this amazing product is proof of their lack of vision.

  • "Managing Enterprise Content" by Ann Rockley (with Pamela Kostur and Steve Manning). ISBN 0-7357-1306-5 (that's the one I have on my desk right now, not sure if there's a newer one).

    It's an easy read, well written and with a sense of humor [note: it's a technical book on ..managing enterprise content. So it's not like "The Hitchhikers Guide to the Galaxy" easy... it's just not "gouge your eyes out after the first chapter" hard], and covers EVERYTHING you haven't thought of. And that most everyone here ha

Slashdot Top Deals

One man's constant is another man's variable. -- A.J. Perlis

Close