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?
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.
Best Answer
I see two good possible approaches to to this problem. However, it's important to realize two things. First, requirements engineering is hard work - turning an idea into a formal specification that is enough to build a system takes a lot of time, effort, and practice. Second, if you have good requirements (in any format, from a formal specification to less formal user stories and use cases), it will be significantly easier, cheaper, and faster to actually build the software (and build it right earlier).
If your friend is either going to be asking for numerous software tools to be built or intends on contracting them out, he should learn how to write software requirements, at least at the level of business objectives and concept of operations. The two leading books on software requirements engineering are by Karl Wiegers - Software Requirements (2nd Edition) and More About Software Requirements: Thorny Issues and Practical Advice. I would expect that most people he would hire would want some kind of document describing the system, at least at a level of business objectives or concept of operations, and these books go into that. They also go into the how and why of other aspects of requirements engineering that I would suspect a good developer would go through early in the project.
The second option would be to either hire someone with experience in software development and requirements engineering (and perhaps even some kind of systems engineering or system architecture) to understand the problem space and determine where software solutions are needed and where software solutions wouldn't be beneficial, write the documents, and perhaps even oversee or carry out the development effort. However, this would probably be more expensive and amount to hiring a full-time software developer for an extended period of time to develop not only the system requested, but the requirements and architecture needed as well.
Honestly, I don't think what your friend is experiencing is that uncommon for someone who doesn't understand the software development process. I also don't think the blame lies entirely on him, either. If the first software project didn't have good requirements, the developer(s) that it was outsourced to should have clarified, refined, and documented the requirements. Frankly, I'm not sure that you are the right person to get involved, either, if you aren't willing to put in the time or the effort to work with the non-technical user/customer and develop good technical specifications (this is a key role of anyone performing requirements engineering in any engineering discipline).
I think the optimal solution is really a combination of my two options. I think that your friend (and perhaps you, as well) should learn about what is involved in requirements engineering and the benefits that having solid requirements can bring to a project. You, as a software developer, should also become more familiar with requirements engineering and how to elicit, document, analyze, and manage requirements as appropriate for software projects - it's really a valuable skill for anyone doing work at any part in the software lifecycle.