Maybe off-topic -- Writing contracts or software specifications

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Maybe off-topic -- Writing contracts or software specifications

Maurí­cio
Hi,

I'm an engineer, and as a programmer I'm just an amateur.
This easied things to me, since I could take decisions about
practices based on what made sense to me.  But now I need
to take responsability for some formal programming tasks,
and I don't know which examples to follow.

I need, for instance, to write a contract with a programmer
we are hiring for a task. But the only example I have of
such contracts seemed to me (as I said, an amateur. I may be
completely wrong) impractical. It was a 150 pages document
with every possible user action and every imaginable allowed
consequences. But it would be easier to me write the software
than such contract itself.

Are there ways already accepted by practice on how to write
software contracts? It's a small program to acquire and show
data from a device, a one person, two months work. I like the
guy we are going to hire, and much to my surprise he sugested
using Haskell for the task. But he also do not have experience
writing such documents.

Thanks,
Maurício

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Manlio Perillo-3
Maurí­cio ha scritto:
> Hi,
>  [...]
> I need, for instance, to write a contract with a programmer
> we are hiring for a task.

 > [...]

The question is: how much do you trust the programmer?
And how much do the programmer trust you?

Much of the complications of the contracts arise from the need to deal
with parts that don't trust each other.


A few pages should suffice.

Make sure that:
1) You explain accurately what the program must do, and how the
    programmer intend to write the program.
    Do you need strong unit tests?
2) Write the deadline for program completion.
    What happens if the deadline is not honoured?
3) Write the estimate price for the work.
    Are price changes allowed?



Regards  Manlio
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Cristiano Paris
In reply to this post by Maurí­cio
On Wed, Apr 8, 2009 at 3:07 PM, Maurí­cio <[hidden email]> wrote:
> Hi,
> ...
> Are there ways already accepted by practice on how to write
> software contracts? It's a small program to acquire and show
> data from a device, a one person, two months work. I like the
> guy we are going to hire, and much to my surprise he sugested
> using Haskell for the task. But he also do not have experience
> writing such documents.

It depends on how clear and stable are the requirements for the
application that must be developed.

If they are very clear and you think they're not going to change
during development, then you can go for a contract having the product
itself as the subject: you'll describe the application, stating all
the requirements and the acceptance tests for each of them. But be
careful: requirements in the software field are very hard to state
clearly and you might end up with yourself spending a lot of time and
effort just to figure out which are to be included and how they're
best described.

On the contrary, if you have only a vague idea of what the software
should do, then I advice you to hire the person for a certain amount
of time. Hence, you're supposed to collaborate closely with this
person to get the job done, mostly controlling the development. In
order to incentivate the person to finish the job before the end of
the contract, I'd put a big bonus if the software satisfies you. The
downside is that you must spend a lot of time in the project and be
competent in evaluating the person's skills for the project, otherwise
you'll end up with paying a person who is basically useless to you.
Maybe you can get help in evaluating the programmer from a friend or a
collegue.

Anything between these two forms of contracts is likely to fail.

My 2 cents.

Cristiano
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Henning Thielemann
In reply to this post by Maurí­cio

On Wed, 8 Apr 2009, Maurí­cio wrote:

> Hi,
>
> I'm an engineer, and as a programmer I'm just an amateur.
> This easied things to me, since I could take decisions about
> practices based on what made sense to me.  But now I need
> to take responsability for some formal programming tasks,
> and I don't know which examples to follow.
>
> I need, for instance, to write a contract with a programmer
> we are hiring for a task. But the only example I have of
> such contracts seemed to me (as I said, an amateur. I may be
> completely wrong) impractical. It was a 150 pages document
> with every possible user action and every imaginable allowed
> consequences. But it would be easier to me write the software
> than such contract itself.
I think such a contract won't help you, because after writing and using
the software, you will always find things, that you now like to do
different from what you wrote into the contract. I think the best to do is
to divide the project into small pieces. If the programmer is not the
right one, this should turn out after the first piece and you can try
another one. I don't expect that you can turn an inappropriate programmer
into a better one using a tight contract.
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

asmith9983
My 2cents on this is. Make sure you use the most appropriate programming language for the task you want to achieve, and hire a programmer  who knows the language really well. Make sure they are productive. i.e. They can type at a fast rate. They know the editor  really well. i.e. They know all the obscure features of ViM, such as abbreviations,functions,keyboard mappings. They know how to create a Make file. As they will know the language really well, they will be able to quickly interpret compile time errors.  As they know the language well, they will be able to work with you creating a really good detailed design. e.g. Abstracting any required objects and their methods. as this is a Haskell list, functions structure. A program design always changes during the implementation as you go through the learning curve of needs. You, the programmer and the customer  will have a fairly continuous dialog  of questions.  Write all these down in such a way you can ensure the programs being written encompass them.  Things will go best if everyone has trust in each other and a commitment to producing  a top quality product.
--
Andrew in Edinburgh,Scotland

2009/4/11 Henning Thielemann <[hidden email]>

On Wed, 8 Apr 2009, Maurí­cio wrote:

Hi,

I'm an engineer, and as a programmer I'm just an amateur.
This easied things to me, since I could take decisions about
practices based on what made sense to me.  But now I need
to take responsability for some formal programming tasks,
and I don't know which examples to follow.

I need, for instance, to write a contract with a programmer
we are hiring for a task. But the only example I have of
such contracts seemed to me (as I said, an amateur. I may be
completely wrong) impractical. It was a 150 pages document
with every possible user action and every imaginable allowed
consequences. But it would be easier to me write the software
than such contract itself.

I think such a contract won't help you, because after writing and using the software, you will always find things, that you now like to do different from what you wrote into the contract. I think the best to do is to divide the project into small pieces. If the programmer is not the right one, this should turn out after the first piece and you can try another one. I don't expect that you can turn an inappropriate programmer into a better one using a tight contract.
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe



_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Jason Dusek
In reply to this post by Maurí­cio
  I think it is important to have clear rules for how you'll
  handle adjustments to the project. It's important to set
  expectations clearly at the outset; however, things change and
  there needs to be respect for that. Nothing that is in writing
  should be allowed to remain incorrect unless it is
  specifically superceded.

  Especially for bright people, it is difficult to go through
  the motions of writing up one's little decisions after the
  fact. Can't we just move forward? Do we need all this
  bureaucracy? It's not just about covering your ass -- you also
  want to be sure that what you remember is what the other party
  remembers. The after-meeting write-up and review is a good
  exercize for that.

--
Jason Dusek
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Maurí­cio
In reply to this post by Henning Thielemann
>> I'm an engineer, and as a programmer I'm just an amateur.
>> This easied things to me, since I could take decisions about
>> practices based on what made sense to me.  But now I need
>> to take responsability for some formal programming tasks,
>> and I don't know which examples to follow.

> I think such a contract won't help you, because after writing and using
> the software, you will always find things, that you now like to do
> different from what you wrote into the contract. I think the best to do
> is to divide the project into small pieces.

Thanks for all sugestions. I do agree with what you and others
said, and that's what I would do. I already worked with others
in my former office, and the result was pretty good with just
some talk, a few pictures and around 5 points in source code
saying "here the world state should be this" kind of comments.

But I have an additional concern: to fit in burocracy.  I need
to write a contract that someone else, who understands just
office applications, not software writing, will need to feel
safe enough with to sign it. It's not that important to have
a good contract, but actually to be able to say "someone else
did it like this, and had no problems". Then I can save that
contract and forget about it. I need something that won't hurt,
more than something that will help development.

(I do trust the programmer. Much to my surprise, he suggested
Haskell as the better option for the job.)

Thanks,
Maurício

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: Maybe off-topic -- Writing contracts or software specifications

Richard A. O'Keefe

On 11 Apr 2009, at 1:40 pm, Maurí cio wrote:
> But I have an additional concern: to fit in burocracy.  I need
> to write a contract that someone else, who understands just
> office applications, not software writing, will need to feel
> safe enough with to sign it. It's not that important to have
> a good contract, but actually to be able to say "someone else
> did it like this, and had no problems". Then I can save that
> contract and forget about it. I need something that won't hurt,
> more than something that will help development.

So "contract" here means "legal document", not "specification".
The really important thing here is the level of trust between the
two parties.  If you have a high level of trust, something along
the lines of "You will do something nice for me and I will pay
you a fair price and we'll keep in touch while this happens"
on the back of a paper napkin will do fine.  If you have a low
level of trust, you'll need a great level of detail, and it still
won't help.  I suspect you're somewhere in the middle.

In that case, what you really need to do is to agree on a
process that will _build_ trust, step by step.  Maybe you can't
explain to each other what the final product should be like.
Can you agree on a _first_ step, to be done in a couple of weeks,
where neither of you has much to lose?  Sign a contract for that.
Because it is by intent a small step, where nobody has much to
lose if you just abandon the whole thing, you shouldn't need a
heavyweight legal document.  Showing that you understand the
other side's need to manage risk will help to build trust.

I don't want to go into details, but heavyweight up-front agreements
can come unpleasantly close to killing a company.

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Maybe off-topic -- Writing contracts or software specifications

Achim Schneider
"Richard O'Keefe" <[hidden email]> wrote:

> If you have a low level of trust, you'll need a great level of
> detail, and it still won't help.
>
Heh. Keep your friends close, your enemies closer.

Freelancing, I was always paid per hour, not per feature. From my
experience, writing something like "The contractor will work closely
with an employee designated by Foo to ensure formal and informal, known
or yet to be discovered, specifications are implemented" is the best
thing you can do. If you have it, mention your QA and its guidelines.
If you don't have it, get both. [1]

It's more than enough to boot a bad teamplayer out of his contract,
doesn't induce frowns in top coders (SNAFU, as those are the ones you
want to hire), does not risk mis-specifying requirements (which, with
legal backing, is also SNAFU) and doesn't take longer and/or cost more
to work out than the program itself (SNAFU, again). Be sure that not
only bugs are fixed, but the reasons they appeared in the first place,
too: That's the secret people writing space shuttle control software and
similar use.


[1] Even if it's just one guy working out things like "Every function
    must be documented" and me getting a bug report saying "Help text
    does not mention how to display help text".
--
(c) this sig last receiving data processing entity. Inspect headers
for copyright history. All rights reserved. Copying, hiring, renting,
performance and/or quoting of this signature prohibited.


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: Maybe off-topic -- Writing contracts or software specifications

Peter Verswyvelen-2
There's one sentence I remember from some Extreme Programming books I read:

"the customer only knows what he wants when he gets it"

:-)


On Tue, Apr 14, 2009 at 11:27 AM, Achim Schneider <[hidden email]> wrote:
"Richard O'Keefe" <[hidden email]> wrote:

> If you have a low level of trust, you'll need a great level of
> detail, and it still won't help.
>
Heh. Keep your friends close, your enemies closer.

Freelancing, I was always paid per hour, not per feature. From my
experience, writing something like "The contractor will work closely
with an employee designated by Foo to ensure formal and informal, known
or yet to be discovered, specifications are implemented" is the best
thing you can do. If you have it, mention your QA and its guidelines.
If you don't have it, get both. [1]

It's more than enough to boot a bad teamplayer out of his contract,
doesn't induce frowns in top coders (SNAFU, as those are the ones you
want to hire), does not risk mis-specifying requirements (which, with
legal backing, is also SNAFU) and doesn't take longer and/or cost more
to work out than the program itself (SNAFU, again). Be sure that not
only bugs are fixed, but the reasons they appeared in the first place,
too: That's the secret people writing space shuttle control software and
similar use.


[1] Even if it's just one guy working out things like "Every function
   must be documented" and me getting a bug report saying "Help text
   does not mention how to display help text".
--
(c) this sig last receiving data processing entity. Inspect headers
for copyright history. All rights reserved. Copying, hiring, renting,
performance and/or quoting of this signature prohibited.


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe