What are the best set of details to give to a programmer to define a project?
Simply put, I know what I want done, but I know nothing about programming and so what is the best way to define my project to a programmer so he/she gives me what I need. i.e project summary, design brief, flow charts?
Avoid assumptions. Spell out with as much detail as you can what you want to be done. Make sure every question can be answered with "yes", "no", or X, where X is a definitive value. Don't leave anything up to interpretation or any maybes in your instructions.
Specify every item that should be available to the end-user, its behavior and style. Make sure YOU know exactly what you want, before you ask someone to code it.
And make sure your document is well organized. I'm sure you can find many white papers on business requirements online.
Lay out your requirements. What do you require to be done. Don't just tell him what you want as an end product but give him a list of short-term and long-term goals.
Like I said... Requirements, Requirements, Requirements.
Write a product requirements document.
http://en.wikipedia.org/wiki/Product_requirements_document
Read this series by Joel Spolsky
http://www.joelonsoftware.com/articles/fog0000000036.html
And here's an example
The best way to specify your requirements are from the user's perspective. If you describe specific use cases to your programmers it makes it a lot clearer. It's helpful to us to know what the user is trying to accomplish with our software so we don't build in any of our own assumptions.
This is really a requirements specification and management problem. I would give them whatever you've got. Try to describe it clearly in simple English (or whatever language is appropriate). If you can flowchart, do that too.
You should expect the programmer to maybe ask a few questions and then go off to think, but you should also expect them to come back with more questions for you, to clarify the requirements. If they don't do that within a week or so, you should check back with them to give them the opportunity to ask.
If the project is amenable to it, you might set up to see early, working prototypes.
There is no one particular way that you use to communicate with a programmer. It is a very generic question and you need to add more details on what you want, what kind of application are you looking for etc.
I personally work a lot on at the UI level of a website and prefer screenshots with every request that we get. A picture is worth a thousand words in my case. A person writing a search engine or a crawler wouldn't need a screenshot at all. I also prefer well written technical specifications on what you expect, when do you want it and some examples.
Also, make sure you review whatever you have specified. Some times, your needs may not be the same as the initial description.
Give them the steps that will be necessary in order for you to get to the desired result out of the page. If you have seen any other pages that look similar to what you want then give that to them as an example. But most importantly be specific about what you want! If you do not know what you want, you cannot expect them to.
Some might disagree, but I generally find that flowcharts usually aren't very valuable.
In my experience it's a bad idea to try to define what you want up front, throw it over the wall and expect a programmer to deliver exectly what you want. The hardest thing about building software is it's complexity, if you specify exactly what you want you have probably provided as much detail as when you had programmed it yourself.
The best thing you can do is to try to work together with the programmer. Find someone who can deliver working software in short increments, once a month or once every two weeks. And give feedback about what you like, what you dont like and what more you want. Try to make sure the programmer gives you tested and working software every time so you can really see how much is done.
This way of working gives you the ability to prioritize exactly what features you find important. You have them implemented first. The downside is that this will cost you more time and effort.
You can use the user stories (used on the SCRUM methodology) to express your needs a user. They describe the functionality of the application, or part of the application, in the point of view of the user. The responsibility of the programmer is than to translate these user stories to code.
Check out Advantages of the “As a user, I want” user story template.
Hope it helps, Bruno Figueiredo http://www.brunofigueiredo.com
It's hard to get a complex idea like an entire working peice of software across in words, that's what a requirements document is for. It's been said in other posts; you need to specify precisely what you want done, leaving absolutely no assumptions. Two people can envision something in very different ways from the same explanation, that's why it is so important to specify what exactly you want done.
Also the prerequisites. Make sure you tell the programmer what environment it should run under, is it for a desktop or a server and how much ram and what operating system?
You don't have to specify HOW it works, that's really the programmers job to figure out. You can guide him on it if you have some ideas, but the programmer should have experience or training enough to design the internals.
Really it's about the externals, you need to be very clear about the inputs required and the outputs required, be they graphical user interfaces or programmatic interfaces. You need to know what you want before he can know what you want!
Whatever you do, write it down, and sign it.
Then give it to them, and agree to be held to the instructions on the paper.
Biggest problem we have as developers are incomplete or mistranslated specifications, and what we would really like is a piece of paper which is crystal clear, and you should be able to come to us with any problem in the project, and it should be referred to in the document in crystal-clear-as-used-by-lawyers terminology.
At least that way we can say "look, we did what you asked, here it is in writing, anything not written here can't be expected of me, its not happening".
This may not sound afwully nice, but trust me, you not liking it will make you try all the harder to get it clear. And if a goal doesn't make it into the paper, don't try something like slip it in later, rewriting the spec after requirements will just result in you getting things overblown.
Plan a milestone, sign it off, do it. Something is missed, it goes to a later milestone. You fail to do this, and it will never ship.
You Of those Downvoting me FYI, everyone I know has this problem. It sucks. I have associates whom were effectively blackmailed by companies overdrawing the specifications trying to slip in stuff that was never even discussed. You can't expect somebody to do something that wasn't prescribed. Its not even possible. Maybe it is in fantasy land or that "corporate reality" thing you're always going on about, but not in the real world.
When building a house, one does not "wing it".
A Home-Handy man built house that is done as they make up their mind on how to do it takes years to build. </rant>
Use the SCRUM methodology.
Describe things in terms of "User Stories" (What a user wants to do).
Describe how "User Stories" Interact with each other.
Let the developer figure out the how.
Get him/her to demonstrate what they have done at regular intervals. If you change your mind or it is not going the way you like then you can update the developer on where he was going wrong and he can update his direction.
Specifications/Requirements and the waterfall methodology have been shown time and again not to work (or should I say provide a method for accurately planing a project).
Just to add to what others have said here, you have to be a LOT more specific if this is an outsourced project versus an in-house project. And I don't care if you outsource to India, China, or the guys down the street - if you're not specific, you're likely to get something that will meet the bare minimum of what you put on paper, but not what you wanted. In house programmers will be more likely to request clarification and do what you mean instead of only what you requested.
You need to find a programmer who has experience writing custom applications for non-technical people. This person should also have technical project management experience. He (or she) should create, with your assistance, a requirements document and a functional specification, which you will sign off on before actual development begins. A person who is truly good at this have lots of experience and will not be cheap, but dealing with non-technical customers is as difficult for a lot of developers as dealing with developers is for you.
Even if you sign off on it, that doesn't mean things can't be changed later. If you want changes, you'll update your documents, and your developer will give you a new estimate of cost and time.
Now for the chicken-or-egg problem. If you aren't technical, how do you find a good software developer? Ask people you know for recommendations. If you need to interview somebody, ask them to bring a sample requirements doc and functional spec. Visit web sites they've developed. To be sure, this will eliminate a lot of fully qualified programmers, as many can't share this type of stuff due to confidentiality issues. But you are in a position where you need to know they can understand your business needs and create a product to solve those needs.
If you aren't satisfied with the requirements document and functional spec, don't continue with that person. Things are bound to get worse, not better. You'll end up throwing good money after bad.
It is truly tough to communicate with a lot of developers. Like finding a doctor, find one you're comfortable with, who listens to you and your concerns, and can repeat those concerns in his own words.
Good luck!
Some good suggestions above from the other posters.
Defining the basics of what you want is a obvious start. But in my experience what can also hurt the process downstream is when exceptions are not considered. These are almost always forgotten until after the software has been developed or late in testing. So put some effort into thinking about how you want the software or process to work when things don't go right. Examples:
Programmers like to help, but not that much...they'd much rather work on the next feature than do production support. But if the exception handling specifications are poor that's exactly what everyone on the project will end up doing.
It can definitely help to spread your requirements process over the development cycle via iterative development. You don't always know what kinds of exceptions you'll need to handle. Some are not driven by the business but by technical issues such as user interface behavior, integration with other systems, etc. Even with this though, the better quality requirements you can deliver sooner, the better the overall process will be.
What are the best set of details to give to a programmer to define a project?
this depends on the project, on your understanding of what you want, and on the programmer's understanding of the business domain. User stories, use-cases, and unit-test descriptions are great, but the programmer's understanding of the business domain is a critical foundation for all of these.
Simply put, I know what I want done, but I know nothing about programming
excellent, the first step is to admit that you need help ;-)
and so what is the best way to define my project to a programmer so he/she gives me what I need. i.e project summary, design brief, flow charts?
none of the above - since you are not a programmer, you will not be able to write these technical descriptions accurately. Nor should you!
as others have noted, you should tell the programmer what you, the user, want to be able to do. Not how to do it, but what the software will enable you to do. "What" is requirements, "how" is design.
First and foremost, though, the programmer must understand the business domain that underlies the requiements. Without this grounding he/she is operating in a conceptual vacuum.
Once the programmer has a clue about your business, then talk about the application(s) that you need.
Proceed slowly, write user stories together, draw screens and make paper mockups together, agree on the how-it-should-work details (with respect to the user) together. Explain to the programmer that since this is your first project you really want to be involved at each step in the start-up process but once you both understand and agree on how the application is to be done - including what tests it must pass in order to be accepted - then you will leave him/her alone to code while still being available for questions.
Do not use an inexperienced developer for this first project, since you will be relying on him/her to teach you good practices.
EDIT: and if you have more than one application to be built over time, choose a developer that you like and that you think you could work with over the long term. Build a relationship with him/her based on mutual trust and respect. There are a lot of really good programmers with zero people skills; avoid them, as they will drive you nuts in the long run.
<sarcasm>Provide specifics and details and you will get exactly what you asked for, not what you wanted.</sarcasm>
Seriously, details are good up to a point.
Don't ever assume the developer understands your trade or even wants to learn it. I have found many, many developers don't really want to understand accounting or radiatiological sciences or whatever other trade you are involved in. If they do take any time to learn, it is only at the most cursory level.
Mundane details or decisions that are fundamental to your trade or workflow will not be obvious to the developers. Something as simple as the field or tab order on a page may lost on the developer because they've never had to input your data. Or the fact that two pieces of data are related may be obvious to you, but they may seem completely disconnected to the developer. Maybe the workflow fits a certain pattern, except when a specific event or situation occurs...
Be prepared to teach them pieces of your trade (even if they don't want to) and make sure they understand what it is you really do. This is the area that I've had the most resistant from developers--they tend to think they understand when in fact they don't. This is not through any malice on their part, just the simple reality that many jobs are easy to learn, but hard to master.
Your best bet is to find a programmer that has a talent at developing specifications from non-technical customers. Word of mouth recommendations from other customers would probably be the most reliable way to find programmers that can do this.
Seriously, this is actually the typical scenario for all developers. The customer usually has no technical background and very little desire to delve into programming issues. They often don't even really know what they want, let alone what is possible. So it falls on the developer's shoulders to bridge the gap, connect with the customer and turn the customer's ideas into technical considerations.
To keep things on track, I'd recommend doing the work on a T&M basis in an iterative manner. Have frequent reviews and demos of the system as it is being developed, give feedback on what you see and re-evaluate the value of the system and the quality of the development that you see. Pull the plug if it feels like it is going pear-shaped.
I am constantly flabbergasted at how bad most non-technical people are at envisioning software solutions before they are delivered. I've sat in countless early project meetings where I could guarantee that every programmer in the room was building up the same picture in their head - including envisioning how subroutine calls will be needed to certain functions - yet the customers in the same meeting aren't on the same page at all. All too frequently, this gulf doesn't become known until the customer actually sees the product, which is exactly what the programmers described in the launch meeting, and they point out some obvious (to them) defect.
That only hurts if the customer doesn't get to see the product until the end of development. So look it early, look at it often, and give feedback.
From my technical point of view :
Most obviously, make no assumptions about how feature X would have to be designed/implemented.
But more importantly, from my recent experience, what happens is that the product owner/client has some habits or use some tools to achieve certain tasks. Then, instead of explaining his practical experience, he abstracts what he thinks as a general concept, and this leads to a communication failure where both sides ( product owner and technicians ) look at each other as clueless dorks. You can't achieve anything together until you all have a common vocabulary. Stop the conversation as soon as something seems unclear and try to define every word.
Some examples :
And, finally, don't try to think of everything upfront, that's too much assumptions to make. Work iteratively. Software is "soft", this means it can change. It's better to make small changes over the time than be stubborn about early assumptions.
As for the project management, recently the SCRUM methodology helped me to sort out all kind of communication failures. At least, because of its transparency such a methodology allows to see what might cause a failure before wasting too much time or money.
A lot of programmers I know are very fast learners, and have an innate knack for spotting inconsistencies, alternatives, and simplifications.
You might do best to teach him about your domain: if you yourself had a good intuition about what needs to be built, he'll figure out the same thing, and then you can discuss details.
Quite possibly, on learning about your domain he will suggest a simpler or radically different solution at a higher level that makes your first problem go away, or an existing tool that you can easily put into use.
If you're trying to define a project to build heated handlebars, an hour talking to a good programmer will lead him to suggest gloves.
I've had this happen to me: a customer was willing to pay me to build something, and after a 20 minute chat I pointed them to an existing open-source tool that solved their problem in the general case. They just didn't have the knowledge or mindset to analyze their problem to that extent.
The most important point in all of this is that this is a dialog: you need to share your knowledge with the developer, and together work towards a solution. Throwing a design brief and a spec over the wall is not enough, because you aren't leveraging their abilities to target the problem.