Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Ask Slashdot: Documenting Scattered Sites and Systems?

timothy posted more than 2 years ago | from the you'll-need-a-lot-of-gasoline-but-only-1-match dept.

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

cancel ×

114 comments

Sorry! There are no comments related to the filter you selected.

How does a "small firm" have so much tech? (0, Funny)

Anonymous Coward | more than 2 years ago | (#38630392)

Christ, find another job already.

Re:How does a "small firm" have so much tech? (4, Insightful)

buchner.johannes (1139593) | more than 2 years ago | (#38630472)

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:How does a "small firm" have so much tech? (2)

hedwards (940851) | more than 2 years ago | (#38630512)

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 common information without overwhelming with false positives.

Re:How does a "small firm" have so much tech? (0)

Anonymous Coward | more than 2 years ago | (#38631572)

I wonder if there is any correlation with the fact that the majority of adult slashdotters seem to be bored and frustrated with their jobs and would quit immediately if they didn't need the money...

Re:How does a "small firm" have so much tech? (0)

MichaelKristopeit500 (2018072) | more than 2 years ago | (#38631578)

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're an idiot.

Re:How does a "small firm" have so much tech? (2)

1s44c (552956) | more than 2 years ago | (#38635548)

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:How does a "small firm" have so much tech? (0)

Anonymous Coward | more than 2 years ago | (#38631582)


Why is the advice on Ask Slashdot so often "quit your job" as if running away from the problem is a good solution?

There's (huge generalization) two kinds of problems that get asked on Ask Slashdot.

1. Ones where a little Googling, and a few questions in a more specific forum would answer the question far better than people on Slashdot would.
2. Huge, intractable, non-technical problems that can't be solved by one person alone, and generally don't provide anywhere near enough detail to define it well.

When people see questions of type 2, they're forced to fill in the details themselves. Usually when people do this it involves assuming the worst. Also, questions of type 2 often involve making cultural, value, or hierarchical shifts within the organization, rather than simple technical solutions. Most people in IT are rather good with the technical end of things, but average, or below with the non-technical parts. People writing into "Ask Slashdot" are doubly unlikely to be good at social changes rather than technical ones.

I think you, and the GP are correct. There's not enough information about what the REAL problem is, and a high degree of suspicion that such a small firm has so much technology is rather odd. At first glance it looks like this is a type-1 problem, but some of the facts point to a hidden type-2 problem. It seems there's a much bigger issue at play here than some simple "scattered documentation" issues.

Re:How does a "small firm" have so much tech? (0)

Anonymous Coward | more than 2 years ago | (#38631800)

Most of the douchebags here are just trolls is why. Give 'em a challenge to prove what you said wrong on tech issues? They run. It's just how they are! Ask sexconker, couchslug, and fatphil (they're good recent examples of that). Most people on /. aren't of "that kind", but the ones who are, ARE the ones you're describing, and a 4 yr. old knows more about IT than the dorks I described do.

Re:How does a "small firm" have so much tech? (1)

msobkow (48369) | more than 2 years ago | (#38633148)

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 tiny little topic pages that deal with definitions and other core information.

Re:How does a "small firm" have so much tech? (1)

1s44c (552956) | more than 2 years ago | (#38635572)

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. As long as the documentation can be read and updated with a minimum of fuss it doesn't really matter what tools are used.

Re:How does a "small firm" have so much tech? (2)

muckracer (1204794) | more than 2 years ago | (#38635808)

> 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:How does a "small firm" have so much tech? (1)

1s44c (552956) | more than 2 years ago | (#38635526)

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:How does a "small firm" have so much tech? (0)

Anonymous Coward | more than 2 years ago | (#38636298)

This is where a good ticket tracking system beats a general wiki.

I understand the problem. You have accomplished the "document how" part of the job... Now you have to FIND those documents when you WANT them!

I find using a ticket/change system that has good search is better that "random" documents. What you are REALLY after is WHY you wrote they and WHEN it applies. I tend to search as much by date as by keyword... Does something happen once a month, a few times a year (time changes), yearly (software renewals), or longer... (predatory backhoe).

I don't know if the Wiki platform you use can let you search by entry date, mod date, user editor, etc... You might have to make some simple mods to add similar function instead of building something else.

Re:How does a "small firm" have so much tech? (1)

jandersen (462034) | more than 2 years ago | (#38636346)

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 Enterprise Edition - which should be able to create things like subject indexes into a collection of documents in various formats; or that's what I have heard.

The problem one always has when trying to index free-format texts is that most texts don't explicitly mention the subject words you are after - like, if you have a text about DNA sequencing, you might want to index it under phrases like "Gene therapy", "Medicine" or similar. I don't know how much work is involved, although I assume one will have to teach the "text indexer" how to identify different subjects from context.

On a final note: I have chosen Oracle simply because I know it - I am sure there are similar features in most large databases.

Re:How does a "small firm" have so much tech? (0)

mounthood (993037) | more than 2 years ago | (#38630616)

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? (3, Insightful)

unimacs (597299) | more than 2 years ago | (#38631992)

Almost 15 years ago I went to work for a company in a very similar role. I did everything from coding to user support to network admin. Now we have about 100 employees and I'm the director of the small IT department (6 employees and two contractors).

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? (2)

klubar (591384) | more than 2 years ago | (#38632604)

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:For 30 employees? (2)

Baki (72515) | more than 2 years ago | (#38635264)

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:For 30 employees? (1)

1s44c (552956) | more than 2 years ago | (#38635590)

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:How does a "small firm" have so much tech? (2)

Darinbob (1142669) | more than 2 years ago | (#38632686)

"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:How does a "small firm" have so much tech? (1)

1s44c (552956) | more than 2 years ago | (#38635608)

"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:How does a "small firm" have so much tech? (1)

truthsearch (249536) | more than 2 years ago | (#38632710)

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:How does a "small firm" have so much tech? (1)

1s44c (552956) | more than 2 years ago | (#38635620)

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 .. (2)

tomhudson (43916) | more than 2 years ago | (#38631192)

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.

Re:You missed the first step .. (5, Insightful)

PPH (736903) | more than 2 years ago | (#38632330)

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:You missed the first step .. (0)

Anonymous Coward | more than 2 years ago | (#38632406)

The purpose of a good ticketing system is to unobtrusively manage time and information. If users have to directly fill out a ticket in a system that tracks user contact, the system has failed.

Re:How does a "small firm" have so much tech? (1)

1s44c (552956) | more than 2 years ago | (#38635518)

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 (1)

rich90usa (1255170) | more than 2 years ago | (#38630434)

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 cheatsheets.

Target users and tasks, not systems (5, Insightful)

wanderfowl (2534492) | more than 2 years ago | (#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.

Hire a consultant (1, Insightful)

GeneralTurgidson (2464452) | more than 2 years ago | (#38630446)

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 (2, Interesting)

Anonymous Coward | more than 2 years ago | (#38630468)

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 (5, Insightful)

vlm (69642) | more than 2 years ago | (#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.

Re:Pretend you're the CIO not the IT guy (1)

alphatel (1450715) | more than 2 years ago | (#38630726)

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:Pretend you're the CIO not the IT guy (1)

tomhudson (43916) | more than 2 years ago | (#38631038)

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.

Re:Pretend you're the CIO not the IT guy (1)

alphatel (1450715) | more than 2 years ago | (#38631656)

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.

Re:Pretend you're the CIO not the IT guy (1)

Dharkfiber (555328) | more than 2 years ago | (#38630978)

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. Failing something sophisticated like that, rely on the OSI model - physical, datalink, network, etc.

Re:Pretend you're the CIO not the IT guy (1)

vlm (69642) | more than 2 years ago | (#38631528)

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 (1)

Hognoxious (631665) | more than 2 years ago | (#38630538)

Don't bother. Nobody will read it anyway.

Re:Don't bother (4, Insightful)

BasilBrush (643681) | more than 2 years ago | (#38630628)

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

Re:Don't bother (3, Interesting)

reboot246 (623534) | more than 2 years ago | (#38630698)

But if you can't be replaced, you can't be promoted.

Re:Don't bother (1)

Anonymous Coward | more than 2 years ago | (#38631372)

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 (5, Insightful)

Zero__Kelvin (151819) | more than 2 years ago | (#38630758)

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

Re:Don't be perceived as a high school kid (0)

Anonymous Coward | more than 2 years ago | (#38632552)

I have to agree with this comment but for different reasons.

Most people don't understand IT or technical tasks and management especially are making decisions about it in complete ignorance. You will have to explain and make them understand what you need to do and hopefully it won't take much for them to realise the enormity of the task that is required to be done. With experience, I have found this usually works rather than just saying it can't be done without extra bodies.

Re:Don't bother (1)

BasilBrush (643681) | more than 2 years ago | (#38633492)

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:Don't bother (1)

1s44c (552956) | more than 2 years ago | (#38635664)

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:Don't bother (1)

BasilBrush (643681) | more than 2 years ago | (#38636446)

"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:Don't bother (2)

David Gerard (12369) | more than 2 years ago | (#38631240)

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. (1)

Anonymous Coward | more than 2 years ago | (#38631826)

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 (4, Informative)

lophophore (4087) | more than 2 years ago | (#38630558)

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.

Look at Spice Works (0)

Anonymous Coward | more than 2 years ago | (#38630594)

Look at Spice Works

Semantic Wiki (5, Interesting)

sperxios10 (848382) | more than 2 years ago | (#38630596)

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:Semantic Wiki (1)

starfishsystems (834319) | more than 2 years ago | (#38631362)

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 through the wiki without getting lost, you can sometimes also identify gaps in both the docs and the IT environment itself. It's a great way to work with senior management.

Re:Semantic Wiki (2)

sperxios10 (848382) | more than 2 years ago | (#38631588)

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 queries resulting in cluster of related entities (hosts, subroutines, data-flows, developers and their capabilities, projects, etc). That way you get the *actual* picture, but only indirectly. But that assumption does not alwayd stand...

Regarding the "gaps", you are quite right. Those departments that lack proper documentation, usually avoid the semantic-wiki altogether. And those that participate in the wikie, spot and fill-in the gaps. I expect that these attitudes come with the territory of beaurocratic companies.

Another interesting observation is the quality of content that each department genarates. Those involved in the marketing produce the most vague page-entities with less interconnections, quite the opposite from the technical stuff that makes a good and innovative use of the wiki. Whenever an administrational person participates, good(tm) things happen, such as resolving HR problems, deciding on postponed decisions, and so on. But those people have hardly the time required to participate.

CMDB: GLPI, I-doit etc (1)

Colin Smith (2679) | more than 2 years ago | (#38631768)

Plus automatic inventory system.

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

Re:CMDB: GLPI, I-doit etc (2)

sperxios10 (848382) | more than 2 years ago | (#38631972)

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 different formats you have multiple choices. I remind you that each wiki-page is at the same time a REST API [mediawiki.org] . And SMW follows this path, providing specific query-parameters for getting query-results as CSV, as XML, as text, as html-tables, or any html-structure. And there are numerous extensions [semantic-mediawiki.org] for embeding the results into google-maps(assuming they are geo-coords), event-calendars (assuming dates), graphs, trees, and many more.

Re:CMDB: GLPI, I-doit etc (1)

csirac (574795) | more than 2 years ago | (#38635564)

+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 experimental OpenLayersPlugin to plot linked data which has long/lat (biological specimen) info.

IMHO the querying capabilities of Foswiki are far stronger than SMW, which I've not really found any way to do indirect queries with, Eg. the somewhat contrived example: Author/Country/Population < 20000000 (where an Author field connects to a topic which has a Country field that connects to a topic with a Population field holding a number less than 20,000,000) is a valid QuerySearch expression in Foswiki, but maybe SMW has a way of doing similar stuff these days.

Disclaimer: I wrote the (still not-out-of-beta) SemanticLinksPlugin to support SMW syntax for ad-hoc data (vs structured DataForms, think table schema) :-)

I was faced with a similar task (1)

sandytaru (1158959) | more than 2 years ago | (#38630606)

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.

Re:I was faced with a similar task (2)

Aviation Pete (252403) | more than 2 years ago | (#38631368)

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:I was faced with a similar task (1)

Anne Thwacks (531696) | more than 2 years ago | (#38631554)

Or you could just use LibreOffice and avoid the learning curve.

Re:I was faced with a similar task (1)

CAIMLAS (41445) | more than 2 years ago | (#38633142)

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 (4, Interesting)

rhadc (14182) | more than 2 years ago | (#38630632)

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 (1)

Gorobei (127755) | more than 2 years ago | (#38630642)

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.

google for 'itil' (4, Insightful)

Bazman (4849) | more than 2 years ago | (#38630654)

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:google for 'itil' (0)

Anonymous Coward | more than 2 years ago | (#38631614)

Avoid ITIL and CMDB like the plague :-) They sound great, but will eat you alive if you give others the authority to "enforce ITIL/CMDB".

Re:google for 'itil' (0)

Anonymous Coward | more than 2 years ago | (#38636352)

What's there to "enforce"? ITIL is a framework. You use it to build your process on top of. Then you enforce your process. If you've been told otherwise you've been lied to, or taught something other than ITIL.

Re:google for 'itil' (0)

Anonymous Coward | more than 2 years ago | (#38636134)

Then get yourself a CMDB

This is interesting as I just realized I have been collecting a CMDB of sorts for my personal computers in the form of latest and previous drivers, manuals and upgrade plans for components and software using the file system. Tying financials, security, network, HR and product life cycles to this and extending it to a company wide perhaps using additional software sounds natural.

Library science/Knowledge management (1)

ahoffer0 (1372847) | more than 2 years ago | (#38630680)

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. (1)

Pirulo (621010) | more than 2 years ago | (#38630770)

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.

Organization is not as important as a good search (2)

kbdd (823155) | more than 2 years ago | (#38630870)

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 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.

Simple. (0)

Anonymous Coward | more than 2 years ago | (#38630924)

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?

mod dDown (-1)

Anonymous Coward | more than 2 years ago | (#38630986)

briiliant plan BSD had become The projecT is in Sure that I've

Consider hiring a technical writer (1)

Gribflex (177733) | more than 2 years ago | (#38631170)

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.

inventory managment (2)

slashmojo (818930) | more than 2 years ago | (#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:inventory managment (0)

Anonymous Coward | more than 2 years ago | (#38631490)

http://www.spiceworks.com/

Re:inventory managment (1)

simpsop (413073) | more than 2 years ago | (#38634976)

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.

Not very technical but... (0)

Anonymous Coward | more than 2 years ago | (#38631320)

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.

Re:Not very technical but... (1)

rathaven (1253420) | more than 2 years ago | (#38632522)

Which is really good for quick docs but gets painful at 20 - 30 GB of images in the docs...

Use the power of your Wiki (2)

ResQuad (243184) | more than 2 years ago | (#38631494)

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 (1)

Anonymous Coward | more than 2 years ago | (#38631714)

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 (1)

CAIMLAS (41445) | more than 2 years ago | (#38631810)

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.

Don't do it at all, unless you've been told to (2)

melted (227442) | more than 2 years ago | (#38632048)

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:Don't do it at all, unless you've been told to (2, Insightful)

Anonymous Coward | more than 2 years ago | (#38632426)

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 accept opportunities when they come up. When management says "I've got a project that we think you'd really be able to help. What would happen if I put someone else in your current position and assigned you to this new project?" I can accurately say that the transition would be fairly short and low-risk. It's really nice to see those old responsibilites go away with only a few hours of transitional knowledge-transfer. I've seen others that are never able to shake the support responsibility from their previous projects and they're forevermore distracted somewhat by having to deal with that.

tldr: Developers and support personnel should create whatever documentation is useful for them. Being unable to transition support to someone else makes you look bad / limits your ability to move up.

Re:Don't do it at all, unless you've been told to (1)

melted (227442) | more than 2 years ago | (#38632946)

>> 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. That's not how it works, you have to take it.

Re:Don't do it at all, unless you've been told to (1)

PPH (736903) | more than 2 years ago | (#38632432)

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 overview of all of the systems interconnections and data flows (at least an E size drawing). The story was; when they presented my potential replacement with the diagram, he quit.

Commonality (1)

rathaven (1253420) | more than 2 years ago | (#38632210)

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 (1)

niftymitch (1625721) | more than 2 years ago | (#38632268)

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 (1)

Anonymous Coward | more than 2 years ago | (#38632470)

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

Re:search (1)

BarfooTheSecond (409743) | more than 2 years ago | (#38634226)

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's better to "publish" their documentation (using online tools) rather than to "archive" MS Word files, deep into some directory trees, in locations only known by them... Management support is required...

der. (0)

Anonymous Coward | more than 2 years ago | (#38632942)

welcome to working in rl

I used graphics as an index (1)

SirSpammenot (1075889) | more than 2 years ago | (#38633524)

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 (1)

Anonymous Coward | more than 2 years ago | (#38634300)

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.

Use a service provider? (1)

Don'tTreadOnMe (686201) | more than 2 years ago | (#38634534)

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.

Too many topics (2)

ljw1004 (764174) | more than 2 years ago | (#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!

Wikicrafting for dummies. (1)

w0mprat (1317953) | more than 2 years ago | (#38635268)

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.

MS OneNote, MindManager, freemind, etc... (1)

deadlydiscs (1505207) | more than 2 years ago | (#38635476)

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.

Document Management System / Incident Tracking (1)

tylke (621801) | more than 2 years ago | (#38636542)

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.

Keep it simple, keep it safe. (2)

son_of_asdf (598521) | more than 2 years ago | (#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.

Secure your documentation (2)

SecurityNut (2549076) | more than 2 years ago | (#38636982)

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

Re:Secure your documentation (1)

son_of_asdf (598521) | more than 2 years ago | (#38637056)

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 (1)

anarcat (306985) | more than 2 years ago | (#38637028)

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 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 [bestpractical.com] 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 [ocsinventory-ng.org] , 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.

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>