IT Employment

General discussion


Putting it in Writing: Can It Break a Career Without It?

By comp1systems ·
Ok...if I haven't learned anything else over the years, it's
"put it in writing." This stems from projects I've been
involved in when information was exchanged verbally, and
later the clients come back and says, "you never said that,"
or, "we never discussed those arrangements," or, "that's not
the quote you gave me." It's an awful position to be in
because, for one, there's no documentation to back it up.
This applies to working on someone's computer as well.
Without the disclosure of set policies that make it clear how
things works, the client thinks one way while I think
another. And it all goes back to the cliche' that the
"customer is always right" even if arrangements were made
verbally. If it's not written down, what else can you do?

In an opinion, I think without having policies well
documented and available to the client, and conversations
noted, it could cause more harm than good and as a tech
repair person, end up losing money than earned.

It's terribly important to "put it writing" because it not only
identifies the policies of operation, but with well kept
notes, it confirms any agreements and arrangements that
were made at the time of the service call.

I truly believe that to protect the business and avoid costly
lawsuits, and other ugly situations everything, and I do
mean everything, should be in writing all the way down to
the last period at the end of a sentence. It's simply good
bookkeeping, business and common sense.

I don't want to sound off my rocker here, it's just a matter
of keeping from getting burned and the client from feeling
burned. Any other thoughts on this?

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Comments

Collapse -

What to document and Tools to help

by Arun.Kumar In reply to Putting it in Writing: Ca ...

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.

Collapse -

Importance of Documentation

by Srinivas Malay In reply to Putting it in Writing: Ca ...

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?

Collapse -

avoid old-school documenting ...

by driedee In reply to Putting it in Writing: Ca ...

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

Collapse -

Document Projects? Yes. But also document code --- FORTRAN code

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


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

Collapse -


by mmarris In reply to Putting it in Writing: Ca ...

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.

Collapse -

Individual Specific...or rather Company Specific

by fmbanker In reply to Putting it in Writing: Ca ...

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


Collapse -

Absolutely Agree

by Kirk Webber In reply to Putting it in Writing: Ca ...

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.

Collapse -

I think you are right!

by kevaburg In reply to Putting it in Writing: Ca ...

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.

Related Discussions

Related Forums