Express yourself

I’ve just spent two hours talking with my developer about his understanding of The System for a new project. It was an excellent learning experience. I was given a lesson in technical writing for someone else. Where I thought I was being detailed, I was confusing the issues.

Now I have a better understanding of what is a good descriptive method for him. With this information I’ll be updating the existing requirements document, for my internal use. It’s an iterative process that will never end, but well worth the trip.

Documenting for Outsourced Development

I love the idea of outsourcing development. It forces you to evolve your business processes and it’s entirely in line with the code re-use paradigm found in programming:

[Try to] write re-useable code.

When you are outsourcing your development (especially when you go off-shore) this becomes:

[Try to] write re-useable documentation.

You can no longer have a casual conversation at the coffee machine* with Fred the Coder about what it was you actually meant when you said, “The system needs to save the booking”. The document must stand by itself, it needs to be portable, it needs to be re-usable.

The document creator has to provide a Rosetta Stone for the project: A record of the non-technical description provided by the client and a cohesive translation into the technical description for the development team. When questions are asked by either group, those answers should be noted and incorporated into the (next) version of the document. Even after sigining off on a final version.

If you can provide the perfect Rosetta Stone, then you will only have minimal interaction with the development team which reduces the management overheads. Badly written documentation results in far too much live translation and that leads to missed dead-lines and budget blow-outs.

*or PS3 or Kitchenette etc.

Expectations, I’ve had a few…

I’m am getting a little involved with this article at Joyent about sticking up for your team, even if that means saying no to a customer. It’s a topic close to my heart, especially as I start up a new project.

The crux of the problem is that a client who doesn’t understand what they are paying for needs to be educated; and that education actually costs the provider money, one way or another. If the cost of educating that client is more than that client is worth to the business when do you cut your losses?

Do you hope to have 99 easy clients for each hard one and have the many pay for the few (the typical approach) or do you show the hard one the door? What if the ratio was 999:1? 9999:1?

What’s the break even level? Is it worth it?

I don’t think there is a simple solution, each situation has to be evaluated individually. Before you go in the room, you need to know what you are willing to spend on educating the client. What proportion of the project is going to be invested in managing the client’s expectations. Who’s going to do it? How will it be done?

Joyent has massive archives of forum posts that deal with almost all the crazy things that can happen in their hosting services, they even have a wiki. Is it enough? For me, Yes. For others?

Even 499:1 is probably worth it…

Post-Implementation Review

After the Initial Specification; Development; Testing and first Live Deployment (Implementation) many companies forget the next step.

Post-Implementation Review.

This can be as short as a five minute meeting to pat everyone on the back for a job well done. The point is this; Is the business happy with the results?

Once the process has been live tested there will be new insight into how things work:

• Were the various steps actually performed in the expected way?
• What was different?
• Did the differences have an impact on the overall process?
• Is it worth trying to improve the results?

IS IT WORTH IMPROVING THE PROCESS?

If there are legitimate complaints about the process, then it needs to be changed and the development cycle starts again. If those complaints aren’t worth resolving then the people involved need to be notified of the decision. That way, when the process is run again, everyone knows what to expect and the process will proceed as smoothly as possible (because you’ll know what areas are going to cause issues and the people involved can adjust their expectations of the outcome). This is how good business processes are developed.

If the outcome isn’t what you expected you have two choices: Change the Process or Change your Expectations.