Slashdot Mirror
Ask Slashdot: Documenting Scattered Sites and Systems?
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?"
Christ, find another job already.
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/ 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 cheatsheets.
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.
Most used stuff on top, however you see it. (or the user community). Extremely vague advice, but just something to help keep rational.
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.
"Science flies us to the moon. Religion flies us into buildings." - Victor Stenger
Don't bother. Nobody will read it anyway.
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
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.
there are 3 kinds of people:
* those who can count
* those who can't
Look at Spice Works
Last year i used MediaWiki's SemanticWiki 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.
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 person (me), I was able to discover and eliminate a lot of duplicate information. If you use the built in heading functions, you can drag and drop sections to reorganize things instantly. Although it took me almost a week of nothing but editing that thing, the result was a booklet that can be updated and edited in about five minutes when necessary.
Occasionally living proof of the Ballmer peak.
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 you to own.
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.
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?
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.
Guns don't kill people; Physics kills people! - John Lithgow as Dick Solomon on Third Rock From The Sun
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 more as an optative learning tool instead of mandatory training.
At least I got to say: -"see?" to management. And I quit after setting up my own little operation.
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 is that organization is much less important than a good search tool.
Make the search tool easy to access and use, and make it work, and people will come to use it by default.
Make sure your tool creates a list of failed hits and sort it by occurrence, and you know what to work on next.
Ask a million wikitards to do it for you.
Sheesh, do your homework. Copyediting is Work[tm], so you create a project for it and you simply take an hour a day, every day, until it is fixed. Are you a sysadmin, or a glorified tape monkey?
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 the long term.
It'll cost a bit extra, but it's likely to get done faster than if you DIY, and you won't have to take as much time off from your existing IT duties.
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/ http://www.tracmor.com/ http://www.pukkapanel.com/ and others mentioned here.. http://www.cyberciti.biz/tips/open-source-it-inventory-control-systems.html or if you use RT there is http://requesttracker.wikia.com/wiki/AssetTracker
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
You need to find out where you are before you can develop a plan to "get from here to there."
So, Step ZERO should be to look around all the systems until you find the previous sucker^WVictim^IT persons' name and email address. You might find it stuffed in a comment in a file called by a cron job, or in the header of a random web page, or some source code, or even in a README file.
Then for Step ONE, you contact them to get the real story of what happened (or at least a second perspective, from someone who was there and doesn't have a reason to downplay the stupidity that caused the current situation), and can begin making informed decisions - such as whether you want to stick around or not.
If you DO decide to stick around, then Step TWO becomes adding YOUR contact info (at least your email address - it can be a throw-away one) to a few places, for the next person. It's just professional courtesy to do so (and in engineering, it's pretty much a requirement - you touch it, you sign and stamp it - we should demand the same level of accountability and professionalism in IT).
Step THREE ... brush up on your BOfH, because you'll need the inspiration and moral support when management doesn't understand why what you think is essential is wasted time to them. And why stuff that makes sense to you simply will NOT GET DONE BY USERS.
Step FOUR ... forget wikis and stuff. The won't edit them, they won't use them. Ditto for bug trackers, ticket systems, etc. Their impression is that you work there in house so they shouldn't have to do that sort of stuff. So, simply tell them to email you for every issue, and you'll look at it when you get the email. If they can't be arsed^troubled to put it in writing, you can't expect to take time away from (point to overflowing inbox) all the ones that people have taken the time to write up properly. Make sure that every time you find an issue yourself, you email yourself as a "reminder". You should quickly end up with a couple hundred emails, just from yourself.
Half the time, they won't bother with the email - they'll go back and figure out that, for example, to print something they have to click on the printer icon (sad but true story). Or they'll ask someone else, while you've just CYA by showing that you already have LOTS to do.
Then at the end of every week, do a simple check of how many emails vs. how many resolved issues. If you can email the boss with a "this week, I had 157 emails about 43 different issues, and 36 were resolved" (and make sure that you send out emails asking for confirmation of every resolved issue for more CYA goodness) you've made progress where it counts - the office politics brown-nose department.
I work at a small school in a group of four techs and we have documentation all over the place from before I started; hidden in folders, on servers, and peoples desktops. Most of the documentation is already created; usually in a word docs with pictures. We own site licenses of MS Office (Windows shop) so I copy and paste text and pictures while keeping the formatting into a OneNote file. Now, I have a central file that can be shared on the network and updated by myself and the other techs on the fly. Also, if I want to add any information from pages on the internet I can just copy and paste it into a new page and synch the onenote document. Any files that are updated frequently (inventory, etc...) I link into the Onenote. This allows me to have all the links organized instead a bunch of shortcuts on my desktop. I've found this to be the simplest, quickest, and easiest way to manage what we have without having to implement a whole new system.
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.
snowulf.com
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.
Plus automatic inventory system.
Seriously. Wikis are horrific databases. Once the information is in there making use of it is a nightmare.
Deleted
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 migrate a Mediawiki to a Semantic Wiki while still maintaining access to the underlying MediaWiki extensions, I'd be all ears (haven't looked into it in a while).
Almost all environments I've been in have had a MediaWiki installation, usually very sparse and useless. What I've done is organize it into a few primary categories and try to provide as much information in a consistent fashion (once making the environment as consistent as possible) so that things can be more easily managed. Those categories, organized on the main page, have typically been:
* Topology Overview - this is where things like VLANs/network segments and their use/functionality, network topology, and the locations/uses for the more important hosts on the network are documented. It's the "start here" section.
* Processes/Procedures, where things like "Server Deployment" or "Workstation Configuration" is documented. These are just stub sections linking to other articles, usually.
* Servers - this is the biggest section. Underneath this section there are sub-categories, largely dependent upon the environment. I've grouped by location as well as role. I suspect a semantic wiki would help in this regard, as it's the most awkward part of the whole thing.
* Individual pages/articles are as you'd expect: a description of the article's topic, with links to other information. There are snippets of things you may or may not need for the given topic (commands, code, whatever) as a high-level view into the topic (and sometimes in HOWTO format).
I then use the various extensions available for book printing of Wikis to provide a printed version of documentation to 'management' (or for my own safe keeping/records). Formatting the wiki for this requires a bit of foresight, but you can use Categories to make it easier.
As an extra step, I've integrated it with Nagios, LDAP, etc. where appropriate to provide restrictive access and a deeper view for the per-system configurations. I frequently have a 'scratch' area where I dump my random documentation as well. I've always been the primary user and maintainer of these wikis, so I can't really say how well they'd scale to n users, but I suspect it's capable.
~/ssh slashdot.org ssh: connect to host slashdot.org port 22: too many beers
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.
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.
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 of the commonalities. For example:
1) Systems that run X Operating System you keep to a specific patch level - document it and on all different versions you currently have work towards standardising them to your specific system versions.
2) Systems that run X Database System or other systems need Y differences to the build. These start to form a version numbered build of your platforms.
3) Specific application installs.
To be honest, you've started a big project and will probably take some time but in my experience there are not tools to specifically help with this - ITIL based servicedesks, even with change/cmdb capabilities are not good bases for documentation and I've investigated 7 different ones so far including market leaders. However the approach I've highlighted above I'd say is the start down a CMDB route.
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.
Truth is stranger than fiction, but it is because Fiction is obliged to stick to possibilities; Truth isn't. Mark Twain.
When you need multiple ways to access data, a good "search function" may be the best way to do it.
What does the firm do. It seems to me like you need 1 file server, 1 mail server and maybe a web server. All can be combined into 1 unix box or MS small office server or an apple server. Step 1 is to simplify.
Step 2 is to give up on the wiki--use a couple of spreadsheets and an word doc (or apple/unix equivs); no one wants to or cares about your 82 page wiki
I'd start pruning like crasy.
welcome to working in rl
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!
1 Dachshund + 1 Dachshunds = A Paradox.
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 from will pay for itself over time.
3) Consider Confluence for your wiki
You can create a 'space' (think sub-wiki) for each 'domain' and link between spaces. This is what I am doing now. So, each major section and activity in the organisation has a space and everything is linked from the wiki.
Further advice: Build it for yourself at first, populate it with what you need, and let people onboard when they are interested to join you. No one person can build, maintain and hold a wiki by themself, but this is where it starts.
The Confluence API is very good. You can use it to shunt data to and from a CMDB with scripting (perl / python) or java.. it's quite useful. For example, I have a midrange server; the mainframe REXX programs (run by batch JCL) generate reports and other files, and FTP's the data to the midrange serrver. The midrange server has a (batch) perl job which reads these files and updates the CMDB and the wiki pages. All built in a short time using basic tools (REXX, JCL, perl, windows scheduler, Confluence API) strung together.
4) Don't have big empty spaces with lots of blank pages.
If you create a page as a 'marker' great, but do tag the page and put *something* on it. There is nothing worse in documentation than seeing lots and lots of blank pages. Really puts you off.
5) Require everyone who updates your wiki to sign in with their real name.
Stops all sorts of problems. Also have a read of http://www.wikipatterns.com/
6) Take a course in Configuration Management
ITIL will introduce you to CM. It is highly worthwhile to do at least stage 1 CM
For example - http://www.cmtf.com/
7) Get a service desk tool
This gives visibility for what you are working on, and provides a central location for tracking request / problem / issue tickets.
RT3 is free - http://bestpractical.com/rt/
CA Service Desk does the job out of the box - http://www.ca.com/us/service-desk-software.aspx (but the CMDB behind it is not that great, however, the web front end for CA Service Desk is the best I've found / used. Stay away from HP Openview Service Desk - the win32 application will make you, and your users, cry).
This should keep you going for a while. :-)
I'd love to have your job. Good luck!
You have obtained the level of conscious incompetence. Following the advice in this Q&A will bring you to the level of conscious competence quite quickly.
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 have a very detailed overview of the local network. Each geographic location can be scanned in a similar manner, and report back to the central management server.
These types of products are probably cost-prohibitive for the size network that you described, but you may be able to find a local company to work with you to get your stuff documented. If not, there are probably similar tools that are available for a setup of your size.
The advantage of these types of tools is that they track your devices for you, and allow you to query them quickly for almost any information that you would like. You can set up alerts to tell you when a system is three years old, for example, and potentially up for replacement.
These types of tools free you up to do what is probably more important in your case: Dealing with what will make your users more productive.
Good luck! It sounds very exciting.
"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 torture. Personaly I think wikis seldom work well in IT (except perhaps in edgy startups). It ends up being a bog standard corporate intranet that a few people update. Or in the case of the OP, a terrible way to do what Word and Excel do better: Plain Old Documentation.
A wiki is intended to consist of be concise and pertinent, hyperlinked and searchable useful information, and to be just as easy to rapidly update by all participants. (Proper documentation and media would be linked or attached, and topics short and heavily hyperlinked). It's also hardly the last word on technical matters in your organisation. So, considering all that, are you doing wiki right?
It doesn't really work for anything else. In my case, a wiki I set up, nobody really seemed to use it, and were actually afraid to write anything. In your case you have no one else using it. The problem was the people it was for are your typical IT worker, who gets little recognition for initiative, and doesn't find taking initiative to be it's own reward. Far better with a corporate intranet.
You really really need to make good design decisions early on, otherwise once your too far down the path you can't go back and change fundamental decisions, at least not without trashing it all and starting again, or nursing along a steaming heap of fail.
You also need rules, since you can't truly enforce rules (only delude yourself that you can when all you can do is punish breaches), the behavior needs to be an emergent property of how your wiki runs. Set an example: People will see how things have been done so far and copy that style. Give it thought.
Now, you want do's and dont's?
Don't put too much in some wiki pages.
Don't too little in others.
Do link them like crazy. Got tags or keywords? Go nuts with them.
Combine content first bashed out on the wiki into proper technical documents.
Fix your search. Put the search box up front on your main page
Don't overloaded the wiki with things that really didn't need to be there, should be obvious, pure signal to noise ratio.
Now, wikicraft out of the way. As a lone IT guy:
Do write it just good enough to get yourself out of trouble, if and when, you forget shit. Leave gaps.
Do write just bad enough to fuck with the head of your future replacement(s). Strategically placed gaps.
Do write sufficiently useful in the event that you are kept on and management decides to get you some colleagues.Don't turn gaps into a hole for yourself.
After logging in slashdot still does not take you back to the page you were on. It's been that way for 20 years.
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 servers and projects. This last step makes for nice charts and graphs to show managements where things are weak and need improvement and should help to justify additional staff.
Again, I work for Lauren, but it does fit your scenario nicely and it is what I use to manage our development and production servers.
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.
Don't Panic!
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
First, read the PSNA 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, but I'll point you towards Ikiwiki 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 probably extend it.
Make sure people know where your wiki is and *use* it, so it doesn't become this rotten piece of outdated documentation out there. You have only started to understand how this is going to be a pain: documenting is hard long-term work. there's a (bad) reason why people don't do it effectively: it takes time and dedication.
Next you can consider using dedicated tools for certain things like inventory or issue tracking. We have used Request Tracker with good success. It's a very solid product that does a lot, also in Perl, coincidentally enough. It also has the Asset Tracker plugin to follow inventory, but i haven't personnally used that, although I had good feedback from peers that used it successfully in an heterogeneous environment. An alternative is OCS inventory, which I haven't used either.
So, just bite the bullet: you're going in the right direction. Just consider the right tool for the right job is your next step, i guess.
Semantics is the gravity of abstraction
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 documentation. If that chunk is already up to scratch, then work on another.
Third Career: Tree Farmer Second Career: Computer Geek First Career: Teacher, Outdoor Instructor, Photographer.
This is where Google Wave would have shined. That Google pulled the plug on this amazing product is proof of their lack of vision.
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 hasn't thought of. And everything I've forgotten after reading it. Chapter 1 alone will explain the very problem you just described, why it's bad, and why everyone does it.
Seriously - one time through that book has saved me on documentation questions (where to put it, how to organize it, how to write it...) time after time. And I still don't use 90% of what was in it. This is the book that you will read one time, and the concepts stick with you - and save your ass. And make you look like a rock star. A weird, librarian kind of rock star, that isn't fantastically awesome like a real rock star, but that seems to know how to use the dewy decimal system with that extra panache, rock star. People will forget all about it a couple of minutes after checking out their books, but for that one second when they find what they need when they need it and it's all because of you... you'll be the rock star.
Still - your life will be easier.