IT Policies

Documentation: The scourge of my life!

Sometimes the last thing we think of when we learn a new routine is the documentation process, but we know it is a vital, if dull, part of life.

Over the years it has often been necessary to document the work I do on help desks and produce it in a form that can be used as a reference manual for new starters.

-------------------------------------------------------------------------------------------------------------------

Various companies that I have worked for have been working toward ISO 9001 accreditation, and part of this involves having good documentation that can form the basis of the material that is delivered to the new help desker.

It can be hard to write training documentation on a subject that you know well, as many of the steps you perform are done almost subconsciously. The answer to the conundrum is testing. When you have documented a procedure, you should test it, preferably using a test subject who doesn’t do the job regularly.

Whenever I have ignored this simple rule, I have found that a small but vital step has been omitted and the procedure doesn’t work.

To a regular user, the act of pressing Enter is usually taken as read, but unless you know this -- and you can’t assume that everyone does -- the procedure will not work.

You should consider that the whole purpose of writing out procedures is to provide a resource to be used in the event that the person who normally performs a task becomes unavailable. It has always seemed to me to be foolish to allow a situation to develop where knowledge is kept by only one person, but you would be shocked to know how often this happens.

The main reason for documentation is to provide a resource to enable each task to be completed in a uniform manner. Things like password resets, which may require a paper trail and some security checks, need to be done in a completely standardized way. You can get into a lot of arguments if one person manages to get a password reset on request and another has to go through a security procedure, involving getting a manager to request it in a formal manner.

You can’t document everything; most of the work you do on the help desk involves soft skills, which have to be learned through experience. Anyone can learn from a book but being able to ask the right questions, to pacify an angry user, to extract bits of information that the user may not feel to be relevant, and to gain the user's confidence is the real skill of the help desk, and one that sadly seems to be lacking on some of the help desks I call on regularly.

22 comments
Hillwalker
Hillwalker

The worst thing about having tech writing training is that you spend most of your life asking "Who wrote this #$%?" Being a professional in IT (or anything else) does not qualify you as a competent documentation producer. Actually, it's more likely to *dis*qualify you. The practice of documentation is a technology just like any other. How confident would you be with a PC tech who's training was on tractors?

Tony Hopkinson
Tony Hopkinson

then you need ownership, and you need to prove the business need, so some beancounter doesn't cut the resource for it as an optional extra. Documentation is far too often seen as a separate step, usually at the end of project, when the money has run out and the next thing to do needs starting. Obviously you are going to go from none to poor in that scenario. It should be woven into the fabric of the process, don't provide support staff with documentaion, provide them with the ability to generate and maintain useful documents. If you want development documentaion, again build it in, if you can get to teh point where the devlopers look at the documentaion, before they look at the code, they'll keep it up to date for you. The key point is ownership. Documentation is not for the customer, for the auditor, or for management, it should be for us. If it isn't inbuilt, it won't be built....

crnugent
crnugent

...when it's good it's great and when it's bad, it's better than nothing!

kkorf
kkorf

I will tell you the absolute truth here.... My pet peeve is, not having documentation for each project, process, software, and hardware, EVERYTHING... Let me tell you why. I actually had an employee pass away, that held a job, which only he knew how to do, which with small companies. Because, I was fiendish on documentation, a new employee was able to step in and work without losing more than 2-days work time. If this was not in place, we would have shut down for a week or more, which would have ruined us as a business.

jboardman
jboardman

Ah, this is why I can ALWAYS find a job! No one likes to do documentation - and I put "Technical Documentation" first on my resume. Haven't yet seen a company that didn't need a documentation expert, and I have lots of example docs to show them.

raz.abey
raz.abey

My big issue is that the IT resource in my group of companies is very thin on the ground and I find that we have to solve an issue only for another two or three to pop up. By the time your get to documenting the original issue weeks could have passed by! Maybe I need to persuade the managment to hire one extra body (I obviously will not be holding my breath during the budget discussions!)

crowleye
crowleye

We have so many applications, legacy apps, new toys for executives, etc., that even when it has been documented its hard to find anything. We recently started moving all our docs into a wiki. The keyword or text search is so fast that it doesn't matter if one would organize it differently from another, you just search and find it. Helped to eliminate lots of duplicates that needed updating, too.

JohnMcGrew
JohnMcGrew

...and expensive. Years ago, I had a client try to "creep" ISO 9001 into a project. Never mind that the code I'd written was probably the first ever de-facto documentation of the department's processes. I was happy to do it, but only at 4x the cost of the project. Writing code is easy. Good documentation is hard. One tactic that I use is to record myself training people how to use a system, and then transcribing it as the basis for the final documentation. That way, you don't miss the details that you take for granted in your head or fingers.

reisen55
reisen55

Techs included. We poor humans have not had a serious memory upgrade in centuries, and the worst of all situations is when I fix something, find it a good fix, and fail to document the fix so that, six months later, whatever nifty I had was long forgotten. I have to repair something about 2 of 3 times to really remember the procedure. If you don't write it down, it never happened.

razumny
razumny

I couldn't agree more. Though dull, documenting a solution is possibly the most important part of solving a problem. I've solved the problem off it being dull by setting up a thrice weekly blog post schedule for myself, meaning that I have to write content anyway, so why not document how to fix that annoying bug... http://blog.razumny.no

tgreenfield
tgreenfield

Doing documentation is a pain in the butt. I've taken a leaf out of one of my best friend's book. He's a two finger typist, despite having worked in IT for years, but he is able to turn out reams of documentation. How? He uses Snagit (already mentioned) and Nuance's Dragon Dictate. Not uncommon for him to roll out a 25-50page document overnight. I've started using it and it works.

simon.sapsford
simon.sapsford

What Wiki do you find to be the easiest for all to use?

akuji001
akuji001

Along with word and screen shots I use Snagit for documentation. Do you know of any other tools or templates that may be helpful? Thanks

C'Town LarryMac
C'Town LarryMac

That one continues to haunt me from time to time. I keep thinking I've finally learned my lesson and then some obscure problem will come along that I "know" I'll never see again so I struggle with it until I find a fix and then forget all about it. It's even more fun when somebody else remembers that you're the one who fixed that before so they tell everybody to call you because you know how to take care of that...no problem.

TimH.
TimH.

I recently had a job where I was asked to document almost 3,000 applications that were in use but had never been documented. My job was to locate the software, install the software onto a PC and document every step with screenshots so that any engineer could then replicate the install with no problems. 3 years later and they are still using my documentation - not bad eh !!!

marie.truman
marie.truman

We are using MediaWiki for one our systems now and which we can hopefully expand for all of our systems.

tcaroltech
tcaroltech

I use Gadwin Printscreen because it is free. Another tool that I use is 404data.com. It is slick and all web based.

dstellrecht
dstellrecht

The best and most frequently used tool in my arsenal! Whether I want to describe a newly discovered bug to our developer in the UK, or explain to my mother 3000 miles away how to attach that PDF to her email message, it does the job, in 5 minutes or less, with audio!

NickNielsen
NickNielsen

The best source for good documentation is a video recording of the training sessions. You will not only be able to identify steps in the procedure, but will also have documentation of what changes were made and why.

jmgarvin
jmgarvin

Man, it's nice to be able to record a little flash movie of slightly more complex tasks that screenshots won't work for. It makes documenting the ugly processes a little easier.

reisen55
reisen55

How many LOGIN SCRIPTS contain documentation as REM comments? Here a running history of modifications and purpose is VITAL to understanding a complex series of drive and group assignments. But this is invisible documentation. I regularly typed and retained software fix notes, still have more than a few of them. Next: WORK SITE REPORTS. Whenever I visit a client, either remotely or on-site, I write up the purpose of my visit and tasks accomplished. Distribute to key members of client staff as needed or appropriate. Was doing so last night at 11:49 pm due to a database crash, backup 24 hours before available and restored in 40 seconds!!! But I document what I do for management and leave notes for Staff as well. Internal documentation - do not forget it either.

Editor's Picks