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