Designing software and what programmers want

Question

Hey,

I'm working for a company and my job is to serve as a liaison/go-to guy between people who are asking for a piece of software and the software engineers. More precisely, my task could be described as follows: a client wants some sort of new tool/plug in added to their software. Now, my job is to write a clear and thorough report to the software engineers of what they need to do for the client. My report should serve, in some sense, as a blueprint of what they need to do. I was a Physics major (and CS minor) so I know a fair bit about programming so I can write up the materials using flowcharts, simple pictures of what the interface might look like, etc.

Now, I just wanted to know, from a programmer's perspective, what do you want from a hypothetical report like this? In other words, what would an ideal report be for you?

Thanks, Peter

Answer 1

Go to the Joel on Software blog and read everything he writes about "The Spec"

Painless Functional Specifications - Part 1: Why Bother?

Painless Functional Specifications - Part 2: What's a Spec?

Painless Functional Specifications - Part 3: But... How?

Painless Functional Specifications - Part 4: Tips

Answer 2

Unless the person in that role is very good, I'd normally prefer to talk directly to the customer and grasp what they want, then write a specification and produce a prototype, then keep discussing. The possibility of an iterative process (first proposal, review, second proposal, etc.) is essential to me - because it is much more difficult to get the requirements right in your first try.

Answer 3

I want a deep understanding of the user's flow and a precise specification of desired problem-domain behavior.

I want to understand the flow because I may not be familiar with the user's work processes. Understanding their workflow, how they go about their job and how this motivates the desire for the requested change, helps me to better understand what the change may entail. It will help me to provide better estimates of the work required at an earlier stage.

I want to have a precise specification of desired problem-domain behavior because this is likely to be the aspect of the desired project that I'm least familiar with and it's the part that I really need to get "just-right" to wow the user with a finished product. This does not include things like "button X should be disabled"-- as a developer, I can make the basic UI, especially with a good understanding of flow. It does include things like, "X's can't be frobbed if there are no corresponding Y's." Don't presume the implementation in your spec, though suggestions are welcomed if their source and the reasoning behind them are provided.

You have a critical role in the software process, and if you drop the ball, all heck breaks loose. Good luck! :)

Answer 4

The report "like this" is widely known as specification for the project. As for the requirements:

• It should not change in future. At least it's major parts.
• It should describe the whole picture of the future application.
• It should be consistent in terms and structure.
• It must not be controversial.
• It should describe not only the general functionality but all the tricky places as precise as it is possible.

Answer 5

It may be difficult being the liaison to the off-shore developers with no technical person interfacing directly with the clients. This is because it tends to work better if at least a tech-lead type can be involved in an iterative communications process with the client. This allows them to help analyze trade-offs of complexity vs priorities, and to drill down into requirements based on what they see the technical requirements evolving into.

Having a tech lead in on the meetings allows the analysis and design to take place with the customer, rather than without them.

So, basically, you are probably doomed, this is one of the major pitfalls of off-shoring, communications often break-down or don't even get started well.. However, if I was to offer one piece of advice, it would be to get as complete and precise requirements as possible. Drill down as much as possible with the client. Then, allow for a few iterations of questions back and forth between the offshore team and the client with you serving as middle-man.

Answer 6

Unfortunately, as you've probably already identified, what I may see ans an ideal "report" (specification) would be too much for some programmers and too little for others.

What you appear to be talking about here is the Functional specification. Joel's columns (already referenced by another responder) are an excellent start.

For me, the "ideal" includes the following:

1. It should be possible for the Pointy-Haired Boss at your customer's location to read it and understand what it means. They are the one paying for the functionality, and the less they understand it the more likely you are to get asked why your solution doesn't support the ZootleWirtle 9000 file format (or similar).
2. It should differentiate between the required scenarios (if X doesn't work we won't pay you), and the desired ones (we want a green user interface).
3. It should define all applicable inputs and outputs (e.g. file formats etc.)
4. It should define any applicable performance constraints.
5. It should not constrain the developer to any specific implementation unnecessarily. (The customer wants the functionality. Unless they expect to integrate your code into their own system they shouldn't care what language your code is written in.)

Good luck!

Answer 7

There is an excellent chance that a detailed spec from the customer will include things that are impossible, stupid, or both. I'm not trying to knock customers, but they do not understand what is and isn't feasible (not having lots of software engineering knowledge and skills in addition to what they're good at), and they typically do not know initially what they want (that's a skill that's apparently closely related to programming).

This means that one-way communications, from the customer to the software guys through you, is not going to work. There needs to be interaction between the customer and somebody skilled at figuring out requirements (very likely not the engineers), and between the customer and somebody who knows what can be done and how easily. Without this, the customer will wind up asking for extremely difficult things that won't make them happy when they get them. (Go ahead, ask me how I know this.)

Joel wrote some very good stuff on specs, but he's in a different position. Fog Creek listens to customers, but according to Joel's writings decides on the features themselves, and decisions are done among people familiar with software in general and the codebase in particular. This is not the situation you're in.

Therefore, the most important thing you can do is establish some two-way communication. The exact form of the spec is less important, but you do want it to be detailed for out-of-country implementation. During the two-way communication, you'll get feedback on the spec, and you'll observe how the engineers use the spec. Refine it from there.

Answer 8

Nothing personal but from experience ...

I think that a middle man that is not a programmer is "A WASTE OF TIME" (to be nice) .... Unless your client doesn't really know what they want... that's where a middle man comes in to play so he can make the clients have a solid idea of what they want... then they should talk directly to a programmer.