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?"
Target users and tasks, not systems (Score:5, Insightful)
Hire a consultant (Score:1, Insightful)
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.
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:Don't bother (Score:5, Insightful)
Agreed, don't bother. In a small company situation, it's good to be irreplaceable.
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.
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: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.
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:Don't do it at all, unless you've been told to (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 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.