IT Employment

You must know what to document. Have a tool to document, which will index, link and store the documents.
Indexing and Linking implies Categories that the tool provides, under whose headings the documentation can be done.
Last but not the least, document what is required only.

By documenting the things will not only protects the business and avoid costly lawsuits, helps one in refering the same for his work.

Documentation acts as a means for communication, documenation helps in preveting defects.

It could be said as "?Know to Document and Document to Know?

Most projects/changes I have been through, were badly documented to start with. I can only suggest the following to avoid getting burned:
- scope correctly and add full impact analysis (not only the 'risks' but also any 'obvious' dependencies etc... you might think it is low risk, but others might think differently). This triggers other team members as they read through the project definition document (PDD).
- add an issue log and a change log to the PDD. These list all issues you have + analysis + decision forward. Keep these logs updated at all times. BTW, this takes less effort than you think so just do it.
- think in products, not activities. Any activity must result in some sort of product(deliverable). Make sure product descriptions are clear and that everyone can understand then. (also read the walkthrough topic here: http://ct.techrepublic.com.com/clicks?c=155923-29363829&brand=techrepublic&ds=5)
- go through everything with your customer and have him signoff or agree on email with the versioned documents.

In general, unless you are a technical writer, you shouldn't write documentation ...
did I get your attention? read on ...

Check the purpose of documentation. If it is to enhance the user experience, you'll need a technical writer.
If you need it to enhance support services, don't bother writing books. Use concept mapping techniques BEFORE the project is defined as scoping/impact vizualization. These maps vizualize the whole effort, incl. dependencies. You can enhance them DURING the project, adding changes and deviations while you go. Effort is really minimal but you END UP with a realtime documented system, in contrast to the usual ill-scoped or incomplete documentation.
Go to http://cmaps.ihmc.us and check the setup of the pages. These are concept maps turned into html. Really usefull to document 90% of the systems.
I agree however that not all knowledge can be documented clearly using concept mapping and that other methods should be used, but I am documenting the full ebusiness code- and content management chain of one of the world's largest consumer electronics companies as we go ... adding new stuff daily and building projects/changes on top of the current concept maps (immediately shows impact).

The writer at Comp1Systems@ certainly makes a strong case for documenting work associated with projects, and I couldn't agree more.

But please permit me to make a sligh divergence, and emphasize the importance of documenting code.

Now, most of you good folks are probably coding in C#, .NET, or Java. But I'm refering to FORTRAN, which --- believe it or not --- is still an oft used language.

With that in mind, let me ask the following. What if you have a FORTRAN module to which you've identified an error? You spend quite a bit of time analyzing it (perhaps days), in order to find the source of the errors. But your notes ("documentation") that you made were on scrap paper, or on knapkins, or on the back of old envelopes --- all of which soon got misplaced and lost once the maintenance is completed. So, when you come back to that same module a year or so later, you've got to start all over.

Why not refactor that FORTRAN module first, using our methodology of "Functional Blocks". (Go to the DOWNLOAD page of our web site at http://www.TheComp-AidCompany.com and download our 18 page technical report, "Overview of The Methodology of Functional Blocks" for a description.)

By refactoring this FORTRAN module right up front, you've accomplished two things: (1) you've found the source of the error, and (2) you've documented the module. Now, if that module ever comes up for maintenance again, or perhaps for enhancement, you're on board so much faster.


Respectfully,

Ronald C. Wackwitz
The COMP-AID Company
New Braunfels, TX 78132

I come from a military environment and "document everything" are words that make or break you. However, I've noticed in the civilian sector, many bosses would rather do away with the notes since they tend to "slow things down and wouldn't get read anyway." I accept their valid points and offer contradictory arguments. If they still disagree I take my own time to write it all down. You never know when the day will come that your notes are important...I'd rather be praised for my foresight than criticised for not doing something I know should have done.

In my last organisation, I had a boss who would constantly ask me to show her in writing if that was what I or she had said the last time we discussed things. It became absolutely necessary to even write down how many phone calls I had made in a day (and to be extreme...how many glasses of water I had in a day). It is obvious why I left the company....

My current employer is the exact opposite of the lady! In the beginning I used to save every single mail that he sent me or every single chat session we had, but I ultimately realised that he knew what he had spoken or if he didn't remember it, he trusted me enough to believe me whenever I contradicted his version of things.

But my first experience was so bad (especially since it was my first job) that I have been badly burned and still do everything possible to safeguard myself.

Having said that...I just recently tore away a whole writing pad of notes that I had made about the discussions I had with my current employer (since he is in office only 10 days a month)...after saving them all on Notepad!

Its a case of Once Bitten Twice Shy! Sometimes, it becomes necessary to play it by the ear, but most of the time go by your instincts.

FMB!

I totally agree with comp1systems, and I believe this applies to more than just the client/service provider relationship. All too many times in government, I've been to meetings where no official notes were captured and published, and entirely too often, people's memories of what was agreed differ considerably (particularly as time moves on). If two people have a meeting and minutes/action items are not captured and reviewed during that meeting, when those two people get up and walk away from the table, there's at least 3 opinions as to what was agreed on.

What today's workplace is about is about covering your own head.

In my case, I have a form that says I am authorised to carry out the work.

Another says the work was carried out successfully.

Another says the last backup made is good to restore.

And so on and so forth.

It is not tricky at all. The client signs to say you can do it. And then the client signs to say they are happy with the work.

When all is said and done, all we can do is what the client said we can do.