Slashdot Mirror
Ask Slashdot: Documenting Scattered Sites and Systems?
First time accepted submitter capriguy84 writes "Six months ago I joined a small firm(~30) where I am pretty much the IT systems guy. I was immediately asked to work on couple of projects without much going through the documentation on what currently exists. So I created new wiki topics everywhere and whenever needed. I am now in a situation where information is scattered across multiple pages and there is lot of overlapping. So I have decided to start a project of re-organizing the wiki so that it makes sense to me and easily accessible for others. I am dealing with 2 disjoint sites, 4 data centers, managing all flavors of Unix, windows, networking, storage, VMware etc. Along with that I have HOWTO guides, cheatsheets, contracts, licensing, projects, proposals and other things that typically exist in a enterprise. Any tips with how to approach? Dos & Don'ts? Recommended reading?"
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.
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.
NB: The message above might reflect my opinion right now, but not necessarily tomorrow or next year.
Having worked in small environments I suggest pretending you're the CIO not just a low level IT drone.
Create your imaginary virtual employees and organize your data appropriately.
Unless you have a really good reason to go project based at the top level, I'm guessing as "CIO" your employees would be mgr operations, mgr development, mgr security/auditing who basically watches the other two or something like that. Take a wild guess what your top three level directories or top level three wiki pages I'm suggesting.
It become an interesting role playing game, sorta. So, if we were big enough to have a guy who did nothing but R+S CCNP/CCIE type stuff, he would probably report to the operations mgr, so R+S type stuff has a wiki page linked from the operations page. If you had an admin/intern of license collation and recording working for the operations mgr, that would probably link off the operations wiki page, etc.
This is also hyper convenient if the boss graciously grants you a summer intern, you can almost instantly trivially drop that person right into your pre-existing "system". Look kid, you're now officially an instant licensing admin, or whatever.
Also in your summary of "stuff" you overlooked written EULAs you provide to your internal customers, request forms to fill out, whatever ticketing system you use, whatever project management system you use... And it seems helpful to have a public or private or whatever wiki or something documenting what metrics, if any, you provide to your boss for review time.
"Science flies us to the moon. Religion flies us into buildings." - Victor Stenger
Consider who will be using the information, why, and when.
Determine the most common use cases for the information you have collected. Then organize the information to suit.
Server died. What do I do?
Add a user: What do I do?
etc. Think about where you will be in a year, and how this information will be used when you have forgotten most of it, or in panic firefight mode, or gone on to another job.
there are 3 kinds of people:
* those who can count
* those who can't
Last year i used MediaWiki's SemanticWiki to describe the systems, projects, human-resources, external-urls and their dependencies of a telecom.
Besides trivial parent-child relations among developers/employees, departments, etc,
i described system dependencies as semantic-relationsships with names like this: part of, invokes, build by, implements, deployed on, etc.
I described developer responsibilities with names like this: maintained by, coded by, external contact, etc.
Finally, the documentation pages and the refs to external-URLs of projects were reorganized by semantic-relations, like this: javadoc, docUrl, webApp, section of, help page, etc.
Agreed, don't bother. In a small company situation, it's good to be irreplaceable.
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!
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.
In a small company that doesn't have a CTO position, and thinks all of that technology isn't very complicated and can be managed by a single guy acting as "pretty much the IT guy" you are already (falsely) perceived as interchangeably replaceable. I remember one particular interview where I met with the CEO to interview and he wanted to low-ball my already quite low suggested salary. He told me that a high school kid could do what he needed. I simply replied: Well then you need to get yourself a high school kid."
I recommend that you start focusing some effort on changing the false perceptions of upper management, because if they don't understand what is involved and why it is important, all your effort will go unappreciated and even the best solution will fall by the wayside the moment they need to save money to buy more staples.
Guns don't kill people; Physics kills people! - John Lithgow as Dick Solomon on Third Rock From The Sun
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!
Have gnu, will travel.