How does IT documenation work?
August 4, 2008 11:53 AM Subscribe
Despite having no training whatsoever, I've gradually become 'the IT guy' at work. I want to get organized and begin building a documentation file but I have no idea where to start.
Although there is a lot I don't know about technology, I am able to help people around the office with small computer problems. And when an issue is beyond my knowledge, I usually end up being a middle-man between the user and the company who handles our larger IT issues.
Well, my role as IT first-responder is growing and I need to get organized. My understanding is that 'documentation' is critical to an effective IT department, but I don't even know what 'documentation' means in this context.
So, what pieces of information are documented by most IT departments? Where/how is this information stored that makes it easy to find when it is needed? [For IT workers] What is your system for documentation and what would you keep/change if you were building a new system?
Although there is a lot I don't know about technology, I am able to help people around the office with small computer problems. And when an issue is beyond my knowledge, I usually end up being a middle-man between the user and the company who handles our larger IT issues.
Well, my role as IT first-responder is growing and I need to get organized. My understanding is that 'documentation' is critical to an effective IT department, but I don't even know what 'documentation' means in this context.
So, what pieces of information are documented by most IT departments? Where/how is this information stored that makes it easy to find when it is needed? [For IT workers] What is your system for documentation and what would you keep/change if you were building a new system?
How to start/stop things. How to rebuild projects (where is the source, what apps do you need, dependencies etc) What jobs run and what do they do. Anything you can think the person that replaces you will need to know in order to keep everything running.
posted by zeoslap at 12:10 PM on August 4, 2008
posted by zeoslap at 12:10 PM on August 4, 2008
The point of documentation is to make it so when they expand your department (or you become redundant), you will not need to "hand feed" the new guy all the time.
Keep that in mind when you are prioritizing IT documentation... "what would I absolutely want Tommy Techworker to know?"
posted by judge.mentok.the.mindtaker at 12:14 PM on August 4, 2008
Keep that in mind when you are prioritizing IT documentation... "what would I absolutely want Tommy Techworker to know?"
posted by judge.mentok.the.mindtaker at 12:14 PM on August 4, 2008
Best answer: First and foremost, create "As-Built" documents for everything you've done yourself. Once you've done that, start writing down the stuff you wished you'd known when you got saddled with the job. Consider those two things your priority. Documentation isn't for your own convenience, it's for the convenience of anyone who has to work with you or in your stead, so get that part settled down before you go charging off into the documentation wilds.
"So, what pieces of information are documented by most IT departments?"
I write up a document for anything I had to figure out myself, so that someone else can follow the process if necessary. These documents are usually very, very short (under 1k of text) unless a given system is insanely complicated. In a larger organization, it also helps to document things like who asked for and authorized a given change, when, and why. My shop is small enough that we skip most of that.
"Where/how is this information stored that makes it easy to find when it is needed?"
We write text files. Those text files are checked in to Subversion, which we tied to the organization's Active Directory system. Anyone I work with can update their working copy of the document base to the latest documentation with a single svn update, or merge their own documentation changes to the trunk. In all matters, the docs in SVN are authoritative. No copy of a document is the real thing. Nothing attached to an email is given more than "working copy" level of importance.
"What is your system for documentation and what would you keep/change if you were building a new system?"
STICK TO TEXT. Fancy formatting doesn't do anyone any good when they just need answers, and binary blob file formats aren't easy to derive useful deltas from. How you diagram things is your own business. As a matter of preference I use a proprietary diagramming tool (OmniGraffle), but export something universally readable like a PNG alongside my working source file.
System-wise, where I work there are two separate document repositories. One for infrastructure and general IT systems, and one for the primary software system used by the business (there's actually another one just for glue scripts and common configuration files, but that's operational stuff, not docs per se). We practice a certain level of change control with both of these: for any given project, the documentation is branched and then re-merged to trunk at project conclusion. This keeps works in progress from cluttering up the documentation describing production systems.
How you break down the document filesystem is all a matter of preference. Something that makes sense for how you get things done might not work in a different shop, and vice versa. So spend some time figuring out how you're going to sort documents. By type? By project? By cost center? Only you could say what will fit your needs.
If I had my druthers, I'd try to get things into a bit more consistent format with document templates of some kind. I'm in the process of redoing a lot of our documentation, so I may well do that this time around.
posted by majick at 12:17 PM on August 4, 2008 [2 favorites]
"So, what pieces of information are documented by most IT departments?"
I write up a document for anything I had to figure out myself, so that someone else can follow the process if necessary. These documents are usually very, very short (under 1k of text) unless a given system is insanely complicated. In a larger organization, it also helps to document things like who asked for and authorized a given change, when, and why. My shop is small enough that we skip most of that.
"Where/how is this information stored that makes it easy to find when it is needed?"
We write text files. Those text files are checked in to Subversion, which we tied to the organization's Active Directory system. Anyone I work with can update their working copy of the document base to the latest documentation with a single svn update, or merge their own documentation changes to the trunk. In all matters, the docs in SVN are authoritative. No copy of a document is the real thing. Nothing attached to an email is given more than "working copy" level of importance.
"What is your system for documentation and what would you keep/change if you were building a new system?"
STICK TO TEXT. Fancy formatting doesn't do anyone any good when they just need answers, and binary blob file formats aren't easy to derive useful deltas from. How you diagram things is your own business. As a matter of preference I use a proprietary diagramming tool (OmniGraffle), but export something universally readable like a PNG alongside my working source file.
System-wise, where I work there are two separate document repositories. One for infrastructure and general IT systems, and one for the primary software system used by the business (there's actually another one just for glue scripts and common configuration files, but that's operational stuff, not docs per se). We practice a certain level of change control with both of these: for any given project, the documentation is branched and then re-merged to trunk at project conclusion. This keeps works in progress from cluttering up the documentation describing production systems.
How you break down the document filesystem is all a matter of preference. Something that makes sense for how you get things done might not work in a different shop, and vice versa. So spend some time figuring out how you're going to sort documents. By type? By project? By cost center? Only you could say what will fit your needs.
If I had my druthers, I'd try to get things into a bit more consistent format with document templates of some kind. I'm in the process of redoing a lot of our documentation, so I may well do that this time around.
posted by majick at 12:17 PM on August 4, 2008 [2 favorites]
Best answer: You are going to need two sorts of documentation:
* For your fellow IT people: What systems have you implemented, installed, or made changes to? What would a new staff member need to know to step into your shoes? You need to provide lots of details. Make what developers call "artifacts"--diagrams, HOWTOs, etc, as needed. Maintain an updated list of your assets--servers, workstations, networking hardware, and annotate each with pertinent changes in their status, location, repairs, etc.
* For non-IT users: You will save yourself a lot of time if you spend some up-front time making HOWTOs for common tasks or common problems that you find yourself addressing frequently. Include lots of screenshots.
Using a wiki to organize these things is a good idea, the content is pretty flexible that way, and generally easy to search. Different audiences and security considerations mean you'll likely need to keep these two bodies of documentation well segregated, so factor that into your plans.
posted by everichon at 12:18 PM on August 4, 2008 [2 favorites]
* For your fellow IT people: What systems have you implemented, installed, or made changes to? What would a new staff member need to know to step into your shoes? You need to provide lots of details. Make what developers call "artifacts"--diagrams, HOWTOs, etc, as needed. Maintain an updated list of your assets--servers, workstations, networking hardware, and annotate each with pertinent changes in their status, location, repairs, etc.
* For non-IT users: You will save yourself a lot of time if you spend some up-front time making HOWTOs for common tasks or common problems that you find yourself addressing frequently. Include lots of screenshots.
Using a wiki to organize these things is a good idea, the content is pretty flexible that way, and generally easy to search. Different audiences and security considerations mean you'll likely need to keep these two bodies of documentation well segregated, so factor that into your plans.
posted by everichon at 12:18 PM on August 4, 2008 [2 favorites]
"Install a wiki on your local machine, or on the network."
I'm going to go against the grain and suggest that as "the IT guy" with a relatively low level of collaboration and an apparent desire to create document artifacts -- files you can store and use and print out and wave around -- a wiki is kind of the opposite of what you want right now. A wiki (of any complexity above a certain level) requires functioning infrastructure to read and write and most of them have no concept of a document in progress. The deltas you generate tinkering around with a document get recorded every time you push the save button, which is convenient but also overwhelming.
Wikis are great when you need to share the task of document authoring with others, but less great when you're just trying to organize and track stuff that could sit in a filesystem of text files readable by anything more powerful than a pocket calculator with no special software, browser, or even functioning network required.
(Having said that, I should mention: orthogonality is a smart dude. If he says to do something, there's a good chance it's useful advice. I just don't happen to agree in this case.)
posted by majick at 12:24 PM on August 4, 2008
I'm going to go against the grain and suggest that as "the IT guy" with a relatively low level of collaboration and an apparent desire to create document artifacts -- files you can store and use and print out and wave around -- a wiki is kind of the opposite of what you want right now. A wiki (of any complexity above a certain level) requires functioning infrastructure to read and write and most of them have no concept of a document in progress. The deltas you generate tinkering around with a document get recorded every time you push the save button, which is convenient but also overwhelming.
Wikis are great when you need to share the task of document authoring with others, but less great when you're just trying to organize and track stuff that could sit in a filesystem of text files readable by anything more powerful than a pocket calculator with no special software, browser, or even functioning network required.
(Having said that, I should mention: orthogonality is a smart dude. If he says to do something, there's a good chance it's useful advice. I just don't happen to agree in this case.)
posted by majick at 12:24 PM on August 4, 2008
I recommend DokuWiki for this purpose
second.
in addition to not requiring a DBMS, it's just really good, and allows for per-section auth, so you have have a public section and a private, login-required section. (where you share your IT seeeeecrets).
posted by judge.mentok.the.mindtaker at 12:25 PM on August 4, 2008
second.
in addition to not requiring a DBMS, it's just really good, and allows for per-section auth, so you have have a public section and a private, login-required section. (where you share your IT seeeeecrets).
posted by judge.mentok.the.mindtaker at 12:25 PM on August 4, 2008
You need more than a "documentation file". A complete picture of how a computer systems environment runs takes a long time to produce, but it's critical that it get produced, because you could win the lottery tomorrow and walk out the door and they'd have no idea what to do.
Documentation, first, means "what do our systems do?" Do you know Visio? If so, build a picture of what your systems environment looks like - your major apps, what kind of boxes they're hosted on, what other systems they interact/connect with, and what their major inputs/outputs are. If you don't know Visio, create a spreadsheet with this info. This "30,000 foot" level will help you get a sense for what the system as a whole looks like, which makes troubleshooting and enhancing easier.
You'll also need a list of jobs that your system runs at night or during the day, and what the inputs/outputs of those jobs are and approximately what time they run (so you know where to start looking if something goes haywire).
You're basically a help desk, so every time you have an interaction with someone about a system problem they're having, think like the help desk and capture the following information (for a smallish company, Excel or Access works for this, but if your company gets bigger you may want to explore a SQL DB or something):
1. What the problem is, in brief
2. What the user was trying to do when the problem occurred
3. What apps the user's PC was running when the problem occurred
And, as you resolve the issue - whether you resolve it yourself or whether you escalate it - make sure you keep a record of what steps you took to resolve the issue. If you escalate it, make sure you can tie the original issue to the escalated solution, for future reference - if your IT vendor gives you a ticket number or some sort of reference number, put that in your original report on the issue, and attach a link/copy of any documentation your IT vendor gives you about the issue.
posted by pdb at 12:25 PM on August 4, 2008
Documentation, first, means "what do our systems do?" Do you know Visio? If so, build a picture of what your systems environment looks like - your major apps, what kind of boxes they're hosted on, what other systems they interact/connect with, and what their major inputs/outputs are. If you don't know Visio, create a spreadsheet with this info. This "30,000 foot" level will help you get a sense for what the system as a whole looks like, which makes troubleshooting and enhancing easier.
You'll also need a list of jobs that your system runs at night or during the day, and what the inputs/outputs of those jobs are and approximately what time they run (so you know where to start looking if something goes haywire).
You're basically a help desk, so every time you have an interaction with someone about a system problem they're having, think like the help desk and capture the following information (for a smallish company, Excel or Access works for this, but if your company gets bigger you may want to explore a SQL DB or something):
1. What the problem is, in brief
2. What the user was trying to do when the problem occurred
3. What apps the user's PC was running when the problem occurred
And, as you resolve the issue - whether you resolve it yourself or whether you escalate it - make sure you keep a record of what steps you took to resolve the issue. If you escalate it, make sure you can tie the original issue to the escalated solution, for future reference - if your IT vendor gives you a ticket number or some sort of reference number, put that in your original report on the issue, and attach a link/copy of any documentation your IT vendor gives you about the issue.
posted by pdb at 12:25 PM on August 4, 2008
I've got an "Administrators Bible" that I keep updated-- I use LaTeX, which enables me to not have to worry about formatting and flow of text, I know that when I hit print, or create a PDF, it'll look like any book you'd buy in the store. It's very simple to learn (if you can do basic html, you're golden) and there are good GUI's to help there too. (I love Kyle, and run a VM especially just to use it).
As for what goes in it-- I simply ask myself, if I disappeared and simply didn't turn up for work, how could I make the next guy's life as easy as possible. I've been in work places where there was nothing and it took me weeks or months to get entirely up to speed. Have respect for people in your field and save that bother for them. (It also prevents you getting phoned on the weekend/holidays!)
I look at my day and essentially document everything that's not totally random. You can do it slowly, pick one task a week-- scratch out basic bullet points initially, something that will give a hint, then when you've got time, go back and expand on them. I fill it in when I've got some dead time, it's certainly not a priority for me, but almost three years in and 112 pages, it's not a great deal of work on a monthly basis.
As mentioned, the current bible sits at 112 pages, it's even got a little introduction that sets out my assumptions (it's not targeted for laymens) and then goes through each major program, and then the processes contained within them. Hardware/software diagnostics, databases and tables/columns that are useful in adhoc reports, quirks with software, best people to deal with with our vendors to skip being passed back and forth.
I have a seperate sheet for passwords that is kept locked away.
Or perhaps a better way to look at it is, imagine you turned up in your current role, it's your first day and you've got no prior experience with the company-- what information would you wish at your fingertips to ensure you could do your job effectively, without hitting dead ends and frustrations? That's your outline.
posted by Static Vagabond at 12:34 PM on August 4, 2008
As for what goes in it-- I simply ask myself, if I disappeared and simply didn't turn up for work, how could I make the next guy's life as easy as possible. I've been in work places where there was nothing and it took me weeks or months to get entirely up to speed. Have respect for people in your field and save that bother for them. (It also prevents you getting phoned on the weekend/holidays!)
I look at my day and essentially document everything that's not totally random. You can do it slowly, pick one task a week-- scratch out basic bullet points initially, something that will give a hint, then when you've got time, go back and expand on them. I fill it in when I've got some dead time, it's certainly not a priority for me, but almost three years in and 112 pages, it's not a great deal of work on a monthly basis.
As mentioned, the current bible sits at 112 pages, it's even got a little introduction that sets out my assumptions (it's not targeted for laymens) and then goes through each major program, and then the processes contained within them. Hardware/software diagnostics, databases and tables/columns that are useful in adhoc reports, quirks with software, best people to deal with with our vendors to skip being passed back and forth.
I have a seperate sheet for passwords that is kept locked away.
Or perhaps a better way to look at it is, imagine you turned up in your current role, it's your first day and you've got no prior experience with the company-- what information would you wish at your fingertips to ensure you could do your job effectively, without hitting dead ends and frustrations? That's your outline.
posted by Static Vagabond at 12:34 PM on August 4, 2008
Response by poster: Thanks everyone for a lot of good advice and guidance. You've taken a lot of stress off my shoulders and replaced it with constructive goals.
posted by wabashbdw at 1:07 PM on August 4, 2008
posted by wabashbdw at 1:07 PM on August 4, 2008
There's nothing worse than getting a folder called 'text files' and being told its the entire documentation for various it/sysadmin/programmatic processes ..... seriously.
posted by shownomercy at 1:52 PM on August 4, 2008
posted by shownomercy at 1:52 PM on August 4, 2008
Best answer: This is more a random collection a thoughts than a coherent narrative, so bear with me:
* The technology you use for documentation is less important than actually doing the documentation. Don't get bogged down into spending a bunch of time trying to make some fancy documentation system work. Any documentation is better than none. I like TiddlyWiki because it's portable and self contained. You might consider a Private TPBWiki as well.
* Backup process. What servers/applications are backed up, when, on to what media (tape, hard drive?) and who has them when they're taken off site?
* Servers. Document how many servers you have, what major applications are installed on each server, the brand and mode number, when the server's warranty expires, the vendor's phone number, whether or not the server has a RAID array and the server's CPU and memory.
* Server-based applications - Document what applications you use, who uses them, what version they are, whether they depend on another supporting application (like a database server).
* Desktop software inventory - Maintain a spreadsheet with your licensed software - the name of the software, number of users, number of licenses. Make sure to record expiration dates on any annual software you buy (antivirus being one).
* Network inventory - Any routers, switches, Internet connection information, including the name and support phone number of your Internet provider, IP addressing information for your various sites. VPN configuration files if you have them.
* How to - This is for anything unusual in your setup. How to install certain applications, how to do confusing tasks or anything you don't repeat often enough to memorize.
That probably isn't everything - it's just off the top of my head. But it's specific and a start.
posted by cnc at 1:53 PM on August 4, 2008
* The technology you use for documentation is less important than actually doing the documentation. Don't get bogged down into spending a bunch of time trying to make some fancy documentation system work. Any documentation is better than none. I like TiddlyWiki because it's portable and self contained. You might consider a Private TPBWiki as well.
* Backup process. What servers/applications are backed up, when, on to what media (tape, hard drive?) and who has them when they're taken off site?
* Servers. Document how many servers you have, what major applications are installed on each server, the brand and mode number, when the server's warranty expires, the vendor's phone number, whether or not the server has a RAID array and the server's CPU and memory.
* Server-based applications - Document what applications you use, who uses them, what version they are, whether they depend on another supporting application (like a database server).
* Desktop software inventory - Maintain a spreadsheet with your licensed software - the name of the software, number of users, number of licenses. Make sure to record expiration dates on any annual software you buy (antivirus being one).
* Network inventory - Any routers, switches, Internet connection information, including the name and support phone number of your Internet provider, IP addressing information for your various sites. VPN configuration files if you have them.
* How to - This is for anything unusual in your setup. How to install certain applications, how to do confusing tasks or anything you don't repeat often enough to memorize.
That probably isn't everything - it's just off the top of my head. But it's specific and a start.
posted by cnc at 1:53 PM on August 4, 2008
Don't reinvent the wheel. If there's a good explanation online, save the url, copy & paste the text into a file.
Use really good naming. A file named "Install Notes" is not as good as "Thingummy v4.6 Install Notes"
Date and sign documents. (wiki will do this automagically)
Document the oddities: Whatsit version 9 requires up-to-date Java. Don't forget to calibrate the schismometer.
Document warranties, software licenses and cd keys. If a printer is broken, is it under warranty? Don't buy another copy of Dreamweaver because you can't find the install key after you reformat a machine. Maybe you can pry it out of Adobe, but if you have it filed, all the better.
Better a few breadcrumbs hinting at a resolution than nothing. cnc is correct; just do the documentation.
posted by theora55 at 2:48 PM on August 4, 2008
Use really good naming. A file named "Install Notes" is not as good as "Thingummy v4.6 Install Notes"
Date and sign documents. (wiki will do this automagically)
Document the oddities: Whatsit version 9 requires up-to-date Java. Don't forget to calibrate the schismometer.
Document warranties, software licenses and cd keys. If a printer is broken, is it under warranty? Don't buy another copy of Dreamweaver because you can't find the install key after you reformat a machine. Maybe you can pry it out of Adobe, but if you have it filed, all the better.
Better a few breadcrumbs hinting at a resolution than nothing. cnc is correct; just do the documentation.
posted by theora55 at 2:48 PM on August 4, 2008
Adding to what others have said, I'd keep it super simple. When you come across a problem, document the steps you took to solve it. When you set up an app, document any configurations steps you took. Print it out, put it in a plastic sleeve and put it into your big binder of knowledge.
posted by gjc at 3:43 PM on August 4, 2008
posted by gjc at 3:43 PM on August 4, 2008
I'm not in IT, a software developer, but I want to n'th the locally installed Wiki concept. Once configured (which may be a pain in the arse), the basics of learning the syntax doesn't take long, 10 minutes and a cheatsheet, readily available, should do the job.
It makes searching easy, inherent revision control, you can embed images and PDF's if required, and it can be useful to the company in general for the same purpose, a central location to store knowledge.
Trying to find info, documents specifically regardless of format, on multiple servers, each with a multitude of folders can be a nightmare, and major waste of time, which is the last thing a company or new employee wants.
Microsoft has Sharepoint, but I found it to be frustrating and useless. I've found Wiki to be much more efficient.
posted by hungrysquirrels at 4:45 PM on August 4, 2008
It makes searching easy, inherent revision control, you can embed images and PDF's if required, and it can be useful to the company in general for the same purpose, a central location to store knowledge.
Trying to find info, documents specifically regardless of format, on multiple servers, each with a multitude of folders can be a nightmare, and major waste of time, which is the last thing a company or new employee wants.
Microsoft has Sharepoint, but I found it to be frustrating and useless. I've found Wiki to be much more efficient.
posted by hungrysquirrels at 4:45 PM on August 4, 2008
Sometimes the same problems happen again and again (new employee, new PC, new version of software installed, expired passwords, person working remotely from home, etc.) If you just keep a log of:
Date+time
Reported problem
Apparent cause
Fix that worked
blank line
You will have a log that you can look back on.
This is not to say that everyone else's suggestions aren't valuable. It's just that this approach is something you can do every day, is quick and easy, and the longer you do it the more valuable the document becomes (when a new problem gets reported you just do a few quick Text finds on keywords you believe would be in any log entry related to the symptoms reported).
posted by forthright at 8:01 PM on August 4, 2008
Date+time
Reported problem
Apparent cause
Fix that worked
blank line
You will have a log that you can look back on.
This is not to say that everyone else's suggestions aren't valuable. It's just that this approach is something you can do every day, is quick and easy, and the longer you do it the more valuable the document becomes (when a new problem gets reported you just do a few quick Text finds on keywords you believe would be in any log entry related to the symptoms reported).
posted by forthright at 8:01 PM on August 4, 2008
I recommend PBwiki as a free online wiki service to get started with, so you'll be able to avoid the initial hassle of setting up your own wiki server (and backups, etc.). Then as you learn stuff, you discipline yourself to take the extra 3 minutes and paste it into a new or existing wiki page. Once in a while when you get bored, you go to the wiki site and arrange the info into some order. The most important thing is to just start piling info into the wiki as you learn it.
If you do decide to go the PBwiki route, send me a MeFi mail and I'll go into further detail about how to configure your PBwiki site to make it easy to use, for both you and everyone else. I'll post that here.
Stay away from SharePoint.
posted by intermod at 8:02 PM on August 4, 2008
If you do decide to go the PBwiki route, send me a MeFi mail and I'll go into further detail about how to configure your PBwiki site to make it easy to use, for both you and everyone else. I'll post that here.
Stay away from SharePoint.
posted by intermod at 8:02 PM on August 4, 2008
This thread is closed to new comments.
posted by orthogonality at 11:58 AM on August 4, 2008