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.

When I need specs from a non-techical client, I usually ask them to write in plain language what exactly it is they want to accomplish. As in “the app should do A to B when I press C, but only if D”. Extra bonus for “because D means that…”.

In fact “take this column and run an average over it.” is a step in the right direction. A better explanation would be “The table contains this and that” (if the structure is predefined); “Get an average of X”. Basically, the least technical way possible without losing the details.

In other words, describe the idea, not the implementation.

Then a caring programmer should be able to understand the actual purpose of what’s he commissioned to do and choose the right steps himself, asking questions for anything non-obvious.

If there isn’t anyone who cares enough and understands the process, the project will fail in any case.

He can try using the storyboard approach.

Have him write down a list of things (stories) the application is going to have to do and within that list, further elaborate on the functionality of each story.

He can use a tool like Asana to flesh out the project scope and functionality, and even interact with his developer.

Translating it into clear requirements is 10x more work than executing
on a clearly written spec.

Amen. That also explains why:

the coder he hired didn’t think through the corner cases and ask appropriate
questions.

Understanding requirements is the hardest (and most expensive) part of most programming projects. When a non-technical person writes requirements they often only document the work-around they want to replace (“open Excel, click on cell B3…”). The best they can hope for is an exact duplicate of their current difficulty!

The most productive way I know to work around this is to encourage this person to write Use Cases (“use” rhymes with “loose”). Instead of writing requirements, describe how the system will be used. This leaves the developer some wiggle-room to suggest a better solution than what the user is doing now.

It sounds like this problem is exacerbated by poor written communication skills on the part of your friend. He/She either has to put the work into effectively communicating their ideas, or pay the programmer to fish the information out of them. Either process is painful and time consuming, but doing it yourself is less expensive than paying someone to do it with you.

In any case, this is a common and frustrating difficulty where creative people either have an incomplete idea, or are incapable of describing it in less than a million words. This person should try to find an extremely patient and insightful programmer who is willing to get to the bottom of what they are really trying to do and make it happen.

the coder he hired didn’t… ask appropriate questions

That’s a recipe for disaster. That, and also the expectation that coder will ask. Coders like to code, not to communicate, expecting them to break their habits without an incentive is pretty unrealistic.

If your friend wants to get job done, they better establish a process involving continuous communication with coder – and it’s your friend who has to play an active role in that, not the coder. “Show me what is done every Monday and set up two hours to discuss this on every Tuesday”, stuff like that.

• For an introduction, supply them some lightweight overviews of iterative and Agile development methodologies (Wikipedia articles will do), so that they get a feeling on how it should be like.
   
• To help them understand past failure, supply them some lightweight overviews of Waterfall / Big Design Up Front (those that include criticism – again, Wikipedia articles will do) – these typically do a pretty good job explaining how it is typically difficult to specify things right up front.

In my experience, most reliable way to get software work as desired with non-technical customers was to permanently communicate and iterate feature descriptions, not trying to specify it to death in one shot.

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.

It is different – it seems a lot simpler than specifying a web app. It’s a logical process. This is the easy stuff.

Your friend very simply needs to write down the steps that he takes when he performs this process. He can do it however he wants but the key things to focus on are accuracy, conciseness, and clarity. There’s no reason that it can’t be done purely in text like a manuscript; it would benefit from some logical division of components or tasks, and would probably work well as a flowchart or diagram.

Now your friend should find a competent analyst/developer and engage their services piece by piece. He needs to lay out his expectations – daily or at least multiple times per week your friend should meet with the developer and see a hands on demonstration of progress. Your friend will pay the developer for his time during these demonstrations, but it will be worth it to ensure that the project is being run to specification. Any changes to the specification – i.e. things that your friend omitted – need to be negotiated and probably added to the quoted price.

Note that I said ‘competent’ – this is not the same as ‘average’, because there are plenty of ‘average’ developers who aren’t competent. If your friend just gets the cheapest coder around, or just finds someone online, he should expect problems. Not to suggest that people who find work online are no good, but you wouldn’t employ someone without a recommendation.

Your friend must simply find the right person. In any software project there is a need for analysts, programmers, system adminstrators, testers, and project managers. The more of these roles your friend wants to ‘outsource’, the more skilled the provider will be and the more your friend should expect to pay.

Sorry to be the one to break this to you, but it’s not a non-technical person’s job to learn how to write formal specifications. It’s the developer’s job to interview the non-technical person, try to distil what the person says to you about what they’re after, determine what it is that the client really wants (as opposed to what it is they think they want, which isn’t always the same thing), build a relatively informal requirements document (one that is well-structured but which tries to avoid jargon that the client won’t understand) and review that document with the client.

Once the client is happy with the informal requirements document, you can use that as a basis for drafting a more formal requirements specification that starts going into more technical detail about what’s needed.

This whole process is known as “requirements capture” and it forms the first step in the software engineering process. Actually writing the software is only a relatively small part of software engineering, a fact that sadly a lot of software developers forget. Another thing they seem to forget is that there is a strong need to communicate with the client and keep a dialogue in place with them during the entire process to ensure that things stay on track.

As for communicating with non-technical people, it’s vitally important you try to avoid using the jargon of computers and software development when talking to them. If they use jargon terms from their own field then it’s important to understand what these terms mean so you might want to draw up a project glossary to get formal definitions for these terms. You’re working for them after all, so it’s important to understand where they’re coming from.

instead of jargon, you should try using non-intimidating ways of communicating with your client, documents written in plain English are a help, but a lot of people in the software business are used to writing for computers rather than humans and so may find this difficult. Additionally, clients don’t like reading through big piles of paper, no matter how plain their language is, so you might want to resort to visual aids. Diagrams, wireframes and storyboards are useful tools here.

But in short, the core point is it’s not your client’s job to learn your language, it’s yours to learn their language.