How to do Software Engineering Contracts

Introduction

Software projects have a notorious reputation of being later than expected, more expensive than estimated and sometimes not even functional.

If you are like me, you are in this field because you want to create great new things. Things that improve lives.

However, you often find that people have:

In a situation where that person is expected to pay you, things can get ugly.

How do things go so sour? Is there an easy way to fix this?

This System Works.

Through trial-and-error I developed a system that avoids all the calamity outlined above and keeps the client happy, willing to pay, and coming back for more.

The client can be lofty and impercise or stubborn and pedantic - it works regardless. The project gets done earlier and cheaper than expected and I still get to sleep and work a reasonable, comfortable number of hours.

Step 1. Get the client to put what they want in prose using normal informal language.

Secretly, we can call this "spec writing" but that sounds really stuffy and formal. You want to keep the hurdles low and goals simple and achievable. It's better not to use words that sounds like a lot of work they don't know how to do.

Instead, ask for user-stories and questions like "How would you envision the finished product to be used?" or "Ok, so how would someone achieve (pick a specific task)?".

A response for a ficticious business idea may look like this:

InstaIce is an ice-cream delivery service.

A user goes to the website and can either proceed as a guest or log in through Facebook.

After logging in, they see their most ordered flavors, the most popular flavors, and the newest ones.

The user clicks on as many flavors as they want and the flavors are added to their cart.

After they are satisfied, they click a "Make me happy" button.

Eat24 then delivers the ice-cream to their door.

Step 2. Break down the prose into tasks.

Edit a copy of the document and stuff incremental numbers between the appropriate words.

You are transforming the prose to an eventual spec that:

Take the exact words and re-arrange them into a numbered form. There are small, subdivid-able tasks hidden in the user-story.

InstaIce is an ice-cream delivery service.

1 A user goes to the website and can either

2proceed as a guest or

3log in through facebook.

After logging in, 4they see

5their most ordered flavors,

6the most popular flavors,

7and the newest ones.

8The user clicks on as many flavors as they want

9and the flavors are added to their cart

After they are satisfied, 10they click a "Make me happy" button.

11Eat24 then delivers the ice-cream to 12their door.

Step 3. Make sure that the client knows about this numbering. Get their approval.

This dividing of the words the client wrote into actual chunks of work is going to be the basis for the contract. The client should see it and agree that you haven't changed the wording and that they haven't left anything out.

Getting a coherent narrative and well-defined product out of this stage of the process is the only goal.

Permit the client to change things or even toss out the previous document and write a brand new one. Nothing is signed yet and it's still early in the game. Changing things now is the easiest and cheapest time to do so.

Step 4. Define What is Needed.

Translate the human prose into technical task items that can be discussed and further sub-divided as needed. They should be phrased in ways that the client can still understand or can be taught the meaning of in under a minute.

This process also helps raise hidden items that everyone at the table may have accidentally glossed over and forgot to talk about.

Feel free to discuss at length exactly what the client means by each word they use. Oftentimes an assumed but mutually conflicting definition left uncheck can lead to a hidden amount of work for you later on.

Everything has to be built, and building things always takes time. And that time, well, you get paid for it. So make sure you get clarity here.

  1. We need a website.
  2. Authentication to the site.
  3. Facebook integration
  4. A store and CMS
  5. An order aggregation function
  6. An aggregation function over all orders
  7. A way to sort by date with a limit
  8. A (probably) ajax cart system
  9. Definition of abandoned cart, etc
  10. Cart commitment, change of state
  11. Eat24 integration
  12. User needs to be a part of Eat24 somehow somewhere.

Step 5. Set the Priorities.

Go back to the client, find out how important these tasks are and how much they value them.

You need to understand what part of the story is more important than others.

Setting priorities at this point instead of earlier allow for the client to have more of an insight into how significant a task may be. When someone understands how long something could take and generally what trouble it is, they can often change their values.

High value

Medium value

Low value

Step 6. Range Estimates.

Use this as an basis for how much effort you should put into each task and do range estimates.

Sometimes a client is willing to do something you would personally think is a phenomenal waste of cash. Other times, they may simply just not care about something you think is really important.

Part of your job is to communicate your professional engineering opinion in order to get to a successful outcome.

Breaking down things like this and telling the client your estimates help keep that clear and coherent.

Giving a range is important since some things have a very high variance. In making estimates, you should ask yourself the following:

Use these answers to form a low and a high end to your estimates. Tell the client both.

High value

Medium value

Low value

Step 7. Arrange Estimates into Weeks.

Programming is hard and exhausting. There are lots of other administrative tasks you need to do in a project besides writing the code. Leave empty time in the week for that by setting aside smaller weeks.

Use the higher numbers to do the calculations and try not to commit yourself to over about 25 hours a week.

Week 1 (18 - 25 hours)

Week 2 (11 - 23 hours)

Week 3 (8 - 19 hours)

Step 8. Commit to the Estimate.

You need to give yourself plenty of room here because however careful you've been

Add up the high end of the estimates (67 hours) and then add the following:

Add it together: 

67 + 25 + 13.4 + 19 + 16.75 = 141.15

Multiply it by your rate (say, $1 an hour, just to be easy.): $141.15.

State the following:

I will get this definition of InstaIce done in 5 weeks for under $141.15.

Give everything to the client, cross fingers.

Step 9. Track all time spent and label it.

Use a time tracker that supports tagging. Use the tags above so that you can see how long you estimated versus how much time you spent.

Only bill the client for the amount of time you actually spend. Claiming you worked hours that you didn't is fraudulant and dishonest.

Maintaining trust with the client is the best way to keep them feeling obliged to pay you for the work. In contracting, compensation dispute is a common occurance after work tendered.

In this system you have a solid audit trail of everything that happened with the client explicitly giving you the thumbs up at every step.

Step 10. Set up weekly meetings.

Go over what you did, what the client expectations were, how long it took you, and how you are looking regarding the big picture.

The client will inadvertently ask for more. Depending on the significance of the ask, demand either part or all of this process again. Some clients need to be taught that "Yes, everything that takes my time, costs you money - sorry."

These meetings can take anywhere from about 1 - 3 hours. Be cautious about charging for them. It's may not always be the right thing to do if you value the client.

Step 11. Success.

When I do this, and stick with it, clients generally have a huge backlog of things that "didn't make it" - another phase that they'd like to do the process on.

That's a sure sign of success: They are following the system, want to continue working with me, and want to do the process again.

The reason the system works is that you've done the three key parts of negotiation: Clarity, Transparency, and Fairness.

Clarity

All parties know what is going to be done and when to expect it. They even authored a way to verify it. At the end, you can go through the initial document and see that their goals have been realized. It's a great feeling.

Transparency

Seeing all those estimate numbers helps the client understand the nature of tasks better and can generally, after a while, know the ballpark even before asking.

Additionally they are never wondering "What are you doing?" or "What's taking so long?" or "How long do I have to wait?". All those questions have been answered before you start. They'll know all those answers weeks in advance.

Fairness

If you are decent at what you do, the client can take your estimates to any competitor and get them independently validated. Additionally, you've accounted for all the hours worked and what you were doing for them. Reciprocity and a debt obligation is now firmly established.

Conclusion

I hope these steps help you avoid the common nightmares in contracting and keep your relationships with your clients healthy and happy.

Thanks for reading. comments

by Chris McKenzie. github