Need help with documentation

[[email protected]]

Hello,

I need help with project documentation. (But not what you think!)

Recently, a customer has switched from "time & materials" invoicing to
"project" invoicing.

But I'm having one heck of a time getting him to write down the
project specifications.

Because projects are scarse, and because I have a long-term
relationship, I've been doing projects with oral descriptions. But
the results are less than optimum, to say the least.

How can I convince the customer that good documentation is to HIS
benefit. FWIW, I wrote a specification for the last project, and he
didn't read it until after I delivered the project.

TIA,
g w helbig -at- yahoo -dot- com

 

[Jeroen Vriesman]

For every project define an extra project called "getting the information
from the customer", and write an extra invoice for that project, make it
more expensive than the project itself.

 

[Jim Thompson]

For every project define an extra project called "getting the information
from the customer", and write an extra invoice for that project, make it
more expensive than the project itself.

[snip]

I've taken to doing just that... the first milestone is "Specification
Resolution" and is payable up-front.

Project cancelable by either party at end of "Specification
Resolution" with no penalty.

I also require a customer sign-off at this point, otherwise the
project self-halts.

(I've had just too many creeping specifications and "wish" lists

...Jim Thompson

 

[markp]

For every project define an extra project called "getting the information
from the customer", and write an extra invoice for that project, make it
more expensive than the project itself.

[snip]

I've taken to doing just that... the first milestone is "Specification
Resolution" and is payable up-front.

Project cancelable by either party at end of "Specification
Resolution" with no penalty.

I also require a customer sign-off at this point, otherwise the
project self-halts.

(I've had just too many creeping specifications and "wish" lists

...Jim Thompson
--

I take the view that a formal specification, which will actually form part
of the contract proper, should be written by the subcontractor him/herself
and not by the customer, and that this work may or may not be separately
invoiced depending on project size. That way the subcontractor must fully
understand, in their own terms, what the customer wants, and the spec then
can't change without re-negotiating the contract. This is the same I guess
as your way of doing things Jim in that the signoff phase is actually
signing the final main contract itself, and as you say it self-halts if not
signed.

Mark.

 

[[email protected]]

Good advice, all.

But how do I convince him he -wants- documentation? In a language he
understands (saves him $).

The push back I get is "you have to be flexable".

 

[Jim Thompson]

Good advice, all.

But how do I convince him he -wants- documentation? In a language he
understands (saves him $).

The push back I get is "you have to be flexable".

Make it a contract requirement that he signs off on the specification
document... no sign, no project.

...Jim Thompson

 

[Spehro Pefhany]

Make it a contract requirement that he signs off on the specification
document... no sign, no project.

...Jim Thompson

Otherwise you'll be slaughtered for sure by the hidden requirements
and changes in specifications... even if they don't intend it to turn
out that way.

Best regards,
Spehro Pefhany

 

[[email protected]]

Make it a contract requirement that he signs off on the specification
document... no sign, no project.

...Jim Thompson

I don't think I'm making myself clear.

What can I show him that will convice him that there is VALUE in doing
the documentation before the project starts?

Non-confrontationally.

If I use your approach, he is likely to say something like: "You
never needed this before, why do you want it now?"

Or, "I don't have time for this".

And take the project elsewhere.

 

[Jim Thompson]

I don't think I'm making myself clear.

What can I show him that will convice him that there is VALUE in doing
the documentation before the project starts?

Non-confrontationally.

If I use your approach, he is likely to say something like: "You
never needed this before, why do you want it now?"

Or, "I don't have time for this".

And take the project elsewhere.

I'm not known to be a "smooth talker", in fact I've been called
"abrasive" many times.

So I can't advise you on how to deal with a cretin.

Sounds like you need him more than he needs you.

I've had a few occasions where the potential customer walked, and went
to a competitor.

And I've had them come back a year or two later on their knees begging
for help. Even had one come back who stiffed me for a milestone
payment on a previous project... he paid up, *then* we talked.

Needless to say, not only do they now agree to a specification
milestone, but the original quote increases in price accordingly

...Jim Thompson

 

[Frank Bemelman]

I don't think I'm making myself clear.

What can I show him that will convice him that there is VALUE in doing
the documentation before the project starts?

Non-confrontationally.

If I use your approach, he is likely to say something like: "You
never needed this before, why do you want it now?"

You want it now, because you are not very happy about the
previous projects.

Or, "I don't have time for this".

Write the specs for him, and let him sign it off. He can
skip reading it, if he likes.

And take the project elsewhere.

That's a possibility.

 

[markp]

I don't think I'm making myself clear.

What can I show him that will convice him that there is VALUE in doing
the documentation before the project starts?

If you really need to, say something like this:

1) It significantly reduces the possibility of misinterpretation of the
specification between you and him.

2) It maximises the chances of swift project success, without major rework
and the time delay this might cause.

3) The early specification can be modified and used by him in his early
promotional documentation.

4) It acts as a common reference for other subcontractors that may be
brought in.

5) It can be used in the process of justifying the raising of funds.

6) It can be used as part of UL or other safety approval procedures at any
stage.

Non-confrontationally.

If I use your approach, he is likely to say something like: "You
never needed this before, why do you want it now?"

As a professional subcontractor you are continually examining how you can
best serve your clients. One way to do this is to maximise the chances of
success on every project you undertake by being thorough about planning and
documentation at all stages, especially at the beginning where the
specification is most open to misinterpretation.

Or, "I don't have time for this".

If he says that you're best out of it anyway, he doesn't recognise that this
way of working is actually beneficial to both parties and that you are
actually doing something to help the project succeed.

And take the project elsewhere.

That's always a possibility whenever you tender for work. Accept that this
might happen, even with established clients.

I wouldn't personally mention anything about other problems you may have had
in the past with other clients. This would be a negative statement in his
eyes, you need to be positive in things you say.

Mark.

 

[Jim Backus]

For every project define an extra project called "getting the information
from the customer", and write an extra invoice for that project, make it
more expensive than the project itself.

[snip]

I've taken to doing just that... the first milestone is "Specification
Resolution" and is payable up-front.

Project cancelable by either party at end of "Specification
Resolution" with no penalty.

I also require a customer sign-off at this point, otherwise the
project self-halts.

(I've had just too many creeping specifications and "wish" lists

...Jim Thompson
--

I take the view that a formal specification, which will actually form part
of the contract proper, should be written by the subcontractor him/herself
and not by the customer, and that this work may or may not be separately
invoiced depending on project size. That way the subcontractor must fully
understand, in their own terms, what the customer wants, and the spec then
can't change without re-negotiating the contract. This is the same I guess
as your way of doing things Jim in that the signoff phase is actually
signing the final main contract itself, and as you say it self-halts if not
signed.

In the good 'ole days of Mil standards what everyone is talking about
would have been known as the SRR or Systems Requirements Review
(MIL-STD-1521B). The idea of a correctly run SRR was that the
contractor turned round the customer's requirements in the
contractor's own words and presented them back to the customer.
English (and probably any other written language) is very imprecise
for expressing requirements, so by agreeing on two different versions
of the requirements both the contractor and the customer were more
likely to end up with what they wanted.

Another good thing to do is to prepare the acceptance criteria for a
specification as early as possible. This has two benefits - firstly
writing a test method for a requirement helps to ensure that it is
clear and testable. Secondly the contractor has already agreed with
the customer the success criteria of the project.

All of the above is basic systems engineering, but after many years in
systems engineering the one thing I've rarely seen done well is any
sort of review.

Perhaps to answer the original question the word to be used is risk
reduction. If you are being paid by milestones, each payment increases
the customer's risk and reduces yours.

As above the MIL-STD-1521 reviews* are a good basis for reviewing any
project - just make sure to tailor the number and detail of the
reviews to fit the project.

* some of the standard reviews are:

SRR = systems requirements review - understand the requirements
SDR = system design review - explain the top level design to the
customer
PDR = preliminary design review - the detail of the design is
substantially complete
CDR = critical design review - the design is essentially complete and
ready for production

... there are others dealing with acceptance and the like.

--
Jim Backus OS/2 user
bona fide replies to jimb-thecirclethingy-jita-dp-demon-dp-co-dp-uk
or remove "NOT" from address
remove dashes and make the obvious substitutions for valid email
address

 

[Ken Moffett]

Hello,

I need help with project documentation. (But not what you think!)

Recently, a customer has switched from "time & materials" invoicing to
"project" invoicing.

But I'm having one heck of a time getting him to write down the
project specifications.

Because projects are scarse, and because I have a long-term
relationship, I've been doing projects with oral descriptions. But
the results are less than optimum, to say the least.

How can I convince the customer that good documentation is to HIS
benefit. FWIW, I wrote a specification for the last project, and he
didn't read it until after I delivered the project.

TIA,
g w helbig -at- yahoo -dot- com

Since the customer has seen fit to change their invoicing, you can
explain the difference between "time and materials" and a "fixed cost"
contracts. Under "time and materials" they could adjust the
specifications as they saw the project unfold, with only incremental
cost increases. But, under fixed contracts, which "they chose", what
they say at the start is what they get, written or verbal. If they don't
want to write it down, suggest a tape recorded session "just to make
sure 'you' don't miss something important" (that they forgot to say).

 

[Active8]

Since the customer has seen fit to change their invoicing, you can
explain the difference between "time and materials" and a "fixed cost"
contracts. Under "time and materials" they could adjust the
specifications as they saw the project unfold, with only incremental
cost increases. But, under fixed contracts, which "they chose", what
they say at the start is what they get, written or verbal.

the bottom line, really.

If they don't
want to write it down, suggest a tape recorded session "just to make
sure 'you' don't miss something important" (that they forgot to say).

recordings, properly done are admissable in court. but cover your ass,
esp. on the phone where it's illegal to record without the other party's
permission which should be asked for and given *after* the tape starts.

there's been some good info given in this thread which i'll put to use
in the future.

for simple projects... i just recently got by with using a statement of
work as a spec *and* a contract. it all fit on one page (BTW OpenOffice
rules! - made the doc without MS word's habit of adding bullets or
capitalizing the beginning of every line just because it thinks like its
idiot creator. the spreadsheet program is a no-brainer, also, if you've
used excel.) i e-mailed it with the suggestion that we use it for the
contract and a request for the enclosure for the project. yeah, fit the
circuit in *this* box or die, mike.

the customer's going to e-mail the box with 2 copies of the SOW, so i
can sign one and send it back. pretty painless. no room for freebie
extras, except i verbally agreed to an LED which i was planning on
anyway

the real bitch is ordering parts and samples aaron!!!!!!!!!!!!!!!

brs,
mike

 

[Spehro Pefhany]

recordings, properly done are admissable in court. but cover your ass,
esp. on the phone where it's illegal to record without the other party's
permission which should be asked for and given *after* the tape starts.

http://www.or-com.com/legal_stuff.htm


Best regards,
Spehro Pefhany

 

[Active8]

http://www.or-com.com/legal_stuff.htm


Best regards,
Spehro Pefhany

thanks. that article was short and sweet. i always err on the side of
safety. the beep switch on my old answering machine was for the record
function, which, per instructions, was to let the other party know it's
recording. yeah, right. more like they'll ask what it is and you'll
remember to tell them. it probably said "in some states..." but the
instructions mentioned the legality of it and if you ever ordered
something on the phone that you saw on TV, you may have been asked for
permission to record.

i've lived in several of those all-party states and here in PA., when i
called to change long-distance service, my local phone company required
3rd-party verification ( a fed thing ) to switch to their LD service.
verification had to get my permission to record.

brs,
mike

 

[JeffM]

"You never needed this before, why do you want it now?"

Try this:
"It's alway been a problem before--trying to guess exactly what you want--
but I value you as a client
so I've been accomodating and worked around it the best I can.
It is becoming a serious problem for me because time IS money
and it seems really easy to avoid any problems
by getting it out of the way up front."

 

[R.Legg]

I don't think I'm making myself clear.

What can I show him that will convice him that there is VALUE in doing
the documentation before the project starts?

Non-confrontationally.

If I use your approach, he is likely to say something like: "You
never needed this before, why do you want it now?"

Or, "I don't have time for this".

And take the project elsewhere.

Unless you've been keeping clear records of previous problems, you
won't be able to convince him that there is a problem.

I keep two sets of records.

The first set is a best budgetary estimate of scheduled resources
needed to complete work at identifiable stages. This includes manhours
(and their source), materials, leadtimes and an outline of the time
when these must be applied in order to meet the deadlines. It is
needed by you to quote on work that is synchronous with activities of
the buyer of your services. It is what you are promising to do -
basically your known contractual obligations at the start of the
program.

The second set is factual - what actually happened. This can be
created after the fact, based on records of activity.

If the two varied by a large degree in a previous program, for reasons
that could be corrected simply by paying more attention to the budget
and schedule - I'm sure he'd be interested. It's one way he can keep
track of all the species of beans, while work is in progress and the
clock is ticking.

Late decisions, that potentially affect deadlines, can be pointed out
and the costs evaluated before they are carved in stone. You may be
able to update the budgetary estimates (basically revising your
contractual obligations) when these added costs are recognized.

The most expensive errors for you are those which introduce delay -
this is time that you are not going to be paid for and may not have
other activities to readily fill in. The most expensive errors for him
are those that require rework or compromise delivery deadlines.
Overhead charges accumulate, whether or not the work is completed to
satisfaction, whether or not your own personal services remain
fixed-price. Sales will be lost.

If there are no customers to influence these decisions, stay clear of
the project unless you're willing to make generous donations to the
company's R&D budget.

RL

 

[Ken Moffett]

thanks. that article was short and sweet. i always err on the side of
safety. the beep switch on my old answering machine was for the record
function, which, per instructions, was to let the other party know it's
recording. yeah, right. more like they'll ask what it is and you'll
remember to tell them. it probably said "in some states..." but the
instructions mentioned the legality of it and if you ever ordered
something on the phone that you saw on TV, you may have been asked for
permission to record.

i've lived in several of those all-party states and here in PA., when i
called to change long-distance service, my local phone company required
3rd-party verification ( a fed thing ) to switch to their LD service.
verification had to get my permission to record.

brs,
mike

I guess that I wasn't thinking of taping a phone conversations, just a
face-to-face. But either way, the idea is to let the customer know
that their verbal specifications are being documented. Since many
people get uncomfortable, because they know they won't remember what
they said, written spec's begin to look more appealing. And that is
what the OP was asking for.

 

[Active8]

[snip]

I guess that I wasn't thinking of taping a phone conversations, just a
face-to-face. But either way, the idea is to let the customer know
that their verbal specifications are being documented. Since many
people get uncomfortable, because they know they won't remember what
they said, written spec's begin to look more appealing. And that is
what the OP was asking for.

well, i didn't really think you meant phone conversations, but i thought
it might be good to warn OP of potential probs. i like your
psychological approach, though. thanks for explaining that.

brs,
mike