How can a non-technical person can learn to write a spec for small projects?

Posted by Joseph Turian on Programmers See other posts from Programmers or by Joseph Turian
Published on 2012-09-03T22:04:00Z Indexed on 2012/09/04 3:48 UTC
Read the original article Hit count: 395

How can a non-technical person learn to write specs for small projects?

A friend of mine is trying to outsource some development on a statistics project.

In particular, he does a lot of work in excel, and wants to outsource the creation of scripts to do what he now does by hand.

However, my friend is extremely non-technical. He is poor at writing technical specs.

When he does write a spec, it is written the way you would describe doing something in excel (go to this cell and then copy the value to that cell). It is also overly verbose, and does examples several times. I'm not sure if he properly describes corner cases.

The first project he outsourced was a failure. I think he overdescribed some details, but underdescribed corner cases. That and/or the coder he hired didn't think through the corner cases and ask appropriate questions. I'm not sure. I got on IM with him and it took me half an hour to dig out a description that should have taken five minutes or less to describe. I wrote the scripts for him at the end, but didn't examine why his process with the coder failed.

He has asked me for help. However, I refuse to get involved, because taking his spec and translating it into clear requirements is 10x more work than executing on a clearly written spec.

What is the right way for him to learn? Are there resources he could use? Are there ways he can learn from small, low-pressure practice projects with coders?

[edit: Most of his scripts are statistical and data processing oriented. e.g. take this column and run an average over it. Remove these rows under these conditions. So the challenge is different than spec'ing a web app.]

© Programmers or respective owner

Related posts about Requirements

Related posts about specifications