Ask Slashdot: Documenting Scattered Sites and Systems? 114
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?"
Re:How does a "small firm" have so much tech? (Score:5, Insightful)
Why is the advice on Ask Slashdot so often "quit your job" as if running away from the problem is a good solution?
I have an issue with my boss --> quit your job
We are using a system that I don't like --> quit your job
In my company, I have this difficulty --> quit your job
As for the original question, I don't think I understand the problem: Of course you have an amount of heterogenous tech to look after. You did a good job organizing it into a wiki. So you already have your information centralized, and just need to maintain it. What's the trouble?
Not sure if the following is applicable to you, but in the last few weeks I dealt with documenting a software package. With sphinx (not limited to python) you write the documentation in the code, and it extracts it to make a nice website. The benefit is that documenting in the same place where you make configuration/software changes is more likely to be maintained. Maybe you can do something similar and build your documentation from the config files, so that centrally, you only tell which config files (etc) you want to pull. The benefit of a wiki is that you don't need any software to change text, and everyone can contribute.
Re: (Score:3)
Sometimes that is the correct solution, however I doubt that's the case with this situation.
The best thing is really to decide on organization ahead of time as you then can keep it organized from the start. Ideally every time one input information that was of general use, one would make some sort of notation about it and create a page linking back to that section of text.
Doing it in retrospect is probably going to be a lot of tedious work as it's unlikely that a simple search is going to reveal all the comm
Re: (Score:2)
Personally I prefer plain old HTML to wiki engines for handling documentation. But I can see where wiki engines are handy because they usually have built-in keyword search capabilities, while an HTML-based documentation approach requires setting up a search engine to scan the pages.
But no matter what approach to take, you will always have some duplication because it makes it easier for the USER of the documentation to understand what you're talking about than having them constantly clicking links to tin
Re: (Score:2)
Personally I prefer plain old HTML to wiki engines for handling documentation. But I can see where wiki engines are handy because they usually have built-in keyword search capabilities, while an HTML-based documentation approach requires setting up a search engine to scan the pages.
I far prefer wiki's. it takes seconds to correct and version a spelling fix in a document in MediaWiki. It takes long enough to wonder if it's worth the effort in plain HTML files. Wiki's make updating documentation easier and give a really easy way to see what changes were made, when, and by whom.
But no matter what approach to take, you will always have some duplication because it makes it easier for the USER of the documentation to understand what you're talking about than having them constantly clicking links to tiny little topic pages that deal with definitions and other core information.
I could not agree more. Personally I'd put the lot in a wiki with well laid out sections, but the choice of tools is a minor consideration compared to the actual effort of writting and updating the documentation.
Re: (Score:3)
> I far prefer wiki's. it takes seconds to correct and version a spelling
> fix in a document in MediaWiki.
How do you deal with the MediaWiki code? That's the biggest stumbling block in my org...nobody wants to learn the syntax of Wiki.
Re: (Score:2)
Re: (Score:2)
Why is the advice on Ask Slashdot so often "quit your job" as if running away from the problem is a good solution?
I have an issue with my boss --> quit your job
We are using a system that I don't like --> quit your job
In my company, I have this difficulty --> quit your job
Maybe many of the people people who post on slashdot are the kind of people who sit at home or in dead end jobs because they run away from challenges.
I really don't get it actually. I love to be given a big mess of systems, clean it up, document it. I find it very rewarding.
Re: (Score:2)
I am in a similar situation, on a somewhat bigger site (50+ UNIXes, large number of dissimilar HW platforms, as well as zSeries, iSeries, HP3000 and other, more exotic HW). I have put all documentation, notes and even ISO images on a single repository, accessible through a Wiki. The problem I have is, that it is hard to find documentation on specific subjects - some of the documentation is in PDFs or DOCs or other formats. The solution I am playing with is to use Oracle Text - it is part of Oracle Enterpris
Re: (Score:2)
Hello Mr Kettle!
This comment may be insightful, but it doesn't address the issue realistically unless one has a time machine. /. answers not providing useful solutions.
Bonus points for the irony of complaining about
Person asks question, discussion ensues, nobody answers the original question as it was asked.
The more things change, the more they stay the same....
Re: (Score:3)
Why is the advice on Ask Slashdot so often "quit your job" as if running away from the problem is a good solution?
because it is precisely their job to deal with the problem themselves. if they don't even know where to start, they aren't quitting as if to run away... they are quitting because they are not qualified.
You may have a point there. You don't get doctors asking on the internet how to treat patients.
you're an idiot.
And you lost it on the pointless abuse.
Re: (Score:1)
You don't get doctors asking on the internet how to treat patients.
Maybe because they don't call it "Ask Slashdot" doesn't mean they don't have / use their own forums to ask other doctors. That's what consultations, looking up journals (which may be on the internet) for cases with similar circumstances, 2nd opinions, sending you to a specialist in the affected area, etc. are for. One could argue that their system is potentially worse due to the fact that you often only get one (or possibly a few) opinions (although the opinions should be more reliable / trustworthy, we al
Re: (Score:1)
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.
Sadly, quitting is the right answer for this problem. If you're "pretty much the IT systems guy" this company doesn't care about IT, and is likely going to fail or undergo some major change soon. Management that only cares about a specific problem (or two) despite disaster looming all around them (IMHO) are always expecting firings. When they're worried about their own job, they'll ignore your concerns and let you do anything, only insisting on the project that will cover their ass if they survive.
Re:How does a "small firm" have so much tech? (Score:4, Insightful)
If the company didn't care about IT they wouldn't have hired a full time tech dude. Jobs like that can be extremely challenging but also extremely fun because you control everything.
Having the technical capabilities we have in a company our size (that isn't a tech company) is rare and allows us to land contracts we'd otherwise not be able to get.
My job has its downsides. It's not for everyone and there's been times I've seriously considered leaving but mostly it's been good. All companies are different and so are the people that work in them. If he likes the job there's no reason he shouldn't keep it unless he thinks the place is headed down the toilet.
For 30 employees? (Score:3)
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.
Re: (Score:3)
Why do you think office-type documents are better at capturing know how than a wiki? My experience is different. Information locked in documents if often hard to retrieve and find. Information in wiki's is searchable, can be linked and connected; it is both easier to find and easier to maintain.
Re: (Score:2)
Re: (Score:2)
You can't tell the guy what to do without knowing his requirements. I assume there is some complexity in there or else he would not need so much kit in the first place.
Wiki's are a good form of easy edit documentation. I'm not sure what you have against them.
Re: (Score:3)
"Quitting" is only an option for those who are independently wealthy, or are egotistical enough to think they can just grab another job by snapping their fingers. Get a new job first before quitting.
Re: (Score:2)
"Quitting" is only an option for those who are independently wealthy, or are egotistical enough to think they can just grab another job by snapping their fingers. Get a new job first before quitting.
Or do a good job instead of quitting.
Re: (Score:2)
If you're "pretty much the IT systems guy" this company doesn't care about IT
One IT guy for an organization of 30 is totally reasonable. Unless their company's focus is in something IT-related (web services, hosting, etc.), one person should definitely be able to manage the IT of a very small company.
Re: (Score:2)
Sadly, quitting is the right answer for this problem. If you're "pretty much the IT systems guy" this company doesn't care about IT, and is likely going to fail or undergo some major change soon. Management that only cares about a specific problem (or two) despite disaster looming all around them (IMHO) are always expecting firings. When they're worried about their own job, they'll ignore your concerns and let you do anything, only insisting on the project that will cover their ass if they survive.
You may be right but you don't know enough about this company to be sure. Maybe one good IT guy is all this company needs once things are neatened up and documented. Getting things in that state is challenging ( i.e. rewarding ) work.
You missed the first step .. (Score:3)
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 wh
Re:You missed the first step .. (Score:5, Insightful)
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.
Been there, done that.
When I was back at Boeing, I put my name in every source code file when I worked on it. After getting shuffled around and finally leaving the company, they decided to outsource support for the whole system. The first thing the vendor did was to find me (by name alone, I'm pretty easy to find in the industry) and hire me as a consultant. That completed the last two steps of my plan:
3) ?????
4) Profit!
Re: (Score:2)
Christ, find another job already.
This guy is doing a the right thing and should be respected for it. Well done to the guy for turning a mess into documented clarity.
If you give up on every task worth performing you will never get anywhere. This guy will get somewhere.
Tool For The Job (Score:1)
Target users and tasks, not systems (Score:5, Insightful)
Hire a consultant (Score:1, Insightful)
usage defines semantics (Score:2, Interesting)
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)
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.
Re: (Score:2)
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.
Re: (Score:2)
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.
Re: (Score:2)
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.
Re: (Score:1)
Re: (Score:2)
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 (Score:2)
Don't bother. Nobody will read it anyway.
Re:Don't bother (Score:5, Insightful)
Agreed, don't bother. In a small company situation, it's good to be irreplaceable.
Comment removed (Score:4, Interesting)
Re: (Score:1)
Don't be perceived as a high school kid (Score:5, Insightful)
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.
Re: (Score:2)
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)
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.
Re: (Score:2)
"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)
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.
Re: (Score:2)
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
Re: (Score:3)
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)
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)
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)
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.
Re: (Score:2)
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
Re: (Score:2)
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
CMDB: GLPI, I-doit etc (Score:2)
Plus automatic inventory system.
Seriously. Wikis are horrific databases. Once the information is in there making use of it is a nightmare.
Re: (Score:2)
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)
+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
I was faced with a similar task (Score:2)
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
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)
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!
Figure out where the costs are (Score:2)
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)
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)
Library science/Knowledge management (Score:1)
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?
It's a great "linchpin" platform. (Score:1)
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
Organization is not as important as a good search (Score:2)
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
Consider hiring a technical writer (Score:2)
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)
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)
Re: (Score:1)
Use the power of your Wiki (Score:3)
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)
BTDT (Score:2)
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)
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)
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)
>> 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)
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
Commonality (Score:1)
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 (Score:1)
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)
When you need multiple ways to access data, a good "search function" may be the best way to do it.
Re: (Score:1)
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
I used graphics as an index (Score:1)
ITIL CM and Confluence and Patterns (Score:1)
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
Use a service provider? (Score:2)
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)
"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!
Wikicrafting for dummies. (Score:2)
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
MS OneNote, MindManager, freemind, etc... (Score:1)
Document Management System / Incident Tracking (Score:1)
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)
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)
Secure your documentation (Score:2)
Re: (Score:2)
mod parent +1 essential. It is awfully easy to set up a painfully insecure documentation system, and rather more difficult to do correctly.
system administration basics (Score:2)
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
Documenting a large system. (Score:2)
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
Google Wave (Score:1)
This is where Google Wave would have shined. That Google pulled the plug on this amazing product is proof of their lack of vision.
The book you need (Score:2)
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