I have taken on a small electronic and software project. It's the first time I'll have done anything like this for reasons other than my own amusement. I'm treating it as a learning experience, and the stakes aren't high. No money is changing hands, but if successful, this may get deployed extensively. I'd like to treat this professionally, including the creation of documentation as part of the finished project.
As a first step, I'd like to write a specification so that project outcomes can be agreed. I'd like some advice on what sort of things should be included, as well as how outcomes should be measured. I'm also happy to read your war stories.
The starting list I've come up with is:
Some kind of Abstract describing the general project.
Who the involved parties are, including who are the decision makers, with contact details.
Time line, including expected milestones.
Must haves/Minimum requirements.
Would like to haves.
Resource allocation (ie. access to initiating party's site, personnel, etc)
Sign-off of the project specification.
What else should I have, or, do I have too much? Even though I am not asking for remuneration, to make this thread useful to more people than myself, by all means discuss money matters if they are relevant to writing a good project specification.
The list you have looks adequate, but the order is wrong. The abstract should be first, obviously. But, that should be followed by the requirements, and then the timeline. Establishing a time line, or even a who's who in the zoo, without requirements is just not possible. So, since you need requirements before a schedule can be created, they should come before the schedule. Whether the who's who list comes before or after the schedule doesn't really matter.
I don't think money matters - whether you are paying or being paid - in terms of developing a good project specification document.
You might want to cover who can make changes to the requirements and to the schedule, and the circumstances under which changes can be made.
Decide up front who will own the copyright to the source code, circuit diagrams and PCB layout.
If you skip this step your customer could claim ownership of everything which could prevent you from using your own creation in future commercial projects for other customers.
MorganS:
I like to write the user manual first. How the end user will interact with the finished project drives a lot of your design decisions.
I like this bit.
If the user is a non-computer person it can actually be quite difficult to write a requirement that the developer and the user both understand to mean the same thing. It is all too easy for both parties to agree on a set of words without realizing that the other guy thinks they have a different meaning. Writing the user manual can be a very effective way of bringing those sorts of misunderstandings to the surface because the user manual must (by definition) be written in terms that the user can understand.
And if the user is a non-computer person it can also be a good idea to build the development of a crude intermediate demo version into the process. The final requirement would not be written until after that demo version had been tried out by the user. Producing a quick-and-dirty demo version can often significantly shorten the total development process by avoiding the need for lots of re-work at the end when it is much more difficult.
Except the user sees the demo and thinks you're finished. That's a bad thing in most projects I've seen.
It's just impossible to show them a house where the front door works but there's no walls and there's no lock on the front door. Nobody would accept such a house as being finished. But a computer program doesn't have visible walls or locks so they don't notice that they're missing.
Paper prototyping is one approach to making a demo that explores the flow of logic without looking like a completed product. However it's actually hard to do, particularly when you're a programmer and it's very easy for you to program a demo on the screen. The user manual can have pictures of the main screens in the program and descriptions of what the buttons do and most people will be able to understand the logic flow and talk about the real work the program does without thinking that the programmer's work is finished.
Now an Arduino project probably doesn't have screens but just a sketch of where the LEDs and buttons are going to be will help the reader of the manual enormously. Suddenly you get questions like "Where's the emergency stop button?" and then you realise that the project needs an emergency-stop function.
My experience tells me you also need a list of "deliverables" to the customer, including the users manual. And since you are building something, a bill of material (BOM) is also necessary.
MorganS:
Except the user sees the demo and thinks you're finished
I suspect you and I are on different wavelengths here. Presumably you would tell the user that the demo is not finished. And I would build it in such a way that it is obviously a rough demo - cheap switches, veroboard etc.
Paper prototyping is also also a good idea. But I think a physical prototype can also be very useful.
I don't know how many things I have made for my own use which worked perfectly as far as I was concerned and the first time I showed it to someone they did something entirely sensible that I had not anticipated and which broke it.
I reckon the user needs to be able to interact with it at an early stage where changes don't cost a lot of time and money. Because it is quite likely those changes will be the result of the user realizing that the original requirement was inadequate.
It is all too easy for a user to say "yes" to a proposed detail of a requirement because they don't understand and are afraid of appearing stupid.
On a slightly different note, I also reckon it is essential to educate the user to understand what it is easy to deliver with a PC and what features would add a large cost to a project. Often some small changes to the user's normal way of doing things makes it enormously easier to computerize. This sort of "education" could also be part of the rationale for the demo.
I reckon the user needs to be able to interact with it at an early stage where changes don't cost a lot of time and money. Because it is quite likely those changes will be the result of the user realizing that the original requirement was inadequate.
Applications that I develop typically have OK and Cancel buttons. All the real work happens when the OK button is pressed. I'll mock up a quick app, that does everything EXCEPT what should happen when the OK button is pressed. That takes less than 10 % of the time, and gives the customer something to play with, while I do the real work.
Changes to the look and feel are isolated from the real work. But, anything obviously missing is noticed right away.
Not particularly relevant to Arduino programming, but worth thinking about. Early customer feedback is essential. It lets them know that you understand what they want.
I've done this a few times. There's a supplier and a client - presumed computer illiterate.
Firstly you must thrash out between you what the client wants in such language as both understand fully. No technical detail is required. Timescales and costs will have to be agreed...
That's the User Requirement Spec - until it's laid in stone, move no further. It's the contract and the bible.
It's a necessary start , and will prevent the inevitable 'project creep' as things progress, which would inevitably slow the delivery.
'save it it for phase two!' is the essential response to modification requests.
The client need not ( and it's probably better if he isn't) be involved in the detailed design and implementation, or the choice of hardware to be employed.
You must agree a project timetable, upon which certain milestones must be provably acheived.
I could go on lots.. estimation, recruitment, premises, project management , testing strategies etc etc.
Robin2:
I suspect you and I are on different wavelengths here. Presumably you would tell the user that the demo is not finished. And I would build it in such a way that it is obviously a rough demo - cheap switches, veroboard etc.
No matter how many times you tell them it isn't finished, if something looks finished then they think that it is. If you've only done the basic functionality and never even tested if the limit switches work, then the customer cannot understand why it takes 3 months (and thousands of dollars) to go from the demo that looked finished to an actual working prototype.
Even a breadboard demo looks finished to someone who thinks all electronics is just a bunch of confusing-looking wires.
"Wow, you did a lot of wiring there! I'll take it now."
