Requirements and you
Part 1 – Introduction and Description of the problem
Part 2 – Requirements and you
Part 3 – Tracking Features and Bugs
Part 4 – The little black book that could
Part 5 – Your developers – Don’t be a prick
Part 6 – Wrapping up
Part 2 – Requirements and you
When you give away a project to be done by someone else, the first thing that you will have to do is to come up with the requirements.
This seems to be easy, and everyone wonders how their projects become so garbled in the process.
Now, here is a little secret:
Writing requirements is hard.
Writing good requirements takes practice, patience and a little secret.
The secret to a good requirements document:
Treat the requirements document as if it would be the only thing that stands between you and checking off the task on a list.
Because that is what it is.
Someone who would not know your project or anything else about what you are trying to do has to be able to look at the list and see if an item has been done. Because this is what is going to happen the moment you enter a dispute over a project outcome and – ultimately – your money.
As this all seems cut and dry, here is a real-life example.
I was working for one of the top international banks as a project manager at the time when this happened.
One part of the project I was involved in (thank you, I was not involved in the part that went south) had the following requirement written down and sent to India.
Requirement 3465x/b: Implement a print button as seen on graphical mockup 577254b.
What happened?
Well, the print button was implemented as per reuirement and mockup from the graphics department. One tiny thing: It would not do anything when clicked on. Yes, you heard that right: Nothing would happen.
Whose fault?
Although it would be easy to blame the programmer (and it was tried) He did NOTHING wrong.
He implemented the feature exactly as requested and specified.
Yes, you could say “But he should have known that it should print the page when clicking on the button.” But I disagree.
Why? Because there are easily a few dozen questions like this:
- How should the printout look?
- Which print function should I implement? Is there a print function available for this program already?
- Should or could we use a third party library?
- Should it print physically or convert the page into a PDF?
- Which part of the pages am I supposed to print?
- Should a legal notice be attached to the printout?
- Which font should I use for printing?
- Should the logo header be included? Where is the high resolution logo?
- …
This is what happens when you write shitty requirement documents.
Another drawback is insecure and less productive coders, as they are having to guess your intentions along the way.
Time and cost estimates done on bad requirements are also way off.
How to write a good requirements document
- Treat the document as what it is: The only evidence of what you want to have done. Telepathy does not enter the picture at any point.
- Divide the document into sections according to screens / pages
- Divide the sections into features / work packages to be done.Each feature should be described in a way that makes it easy to identify it as “done”. For a bonus, it should be possible to identify a good implementation from a bad one.
In the above, badly done requirement, implementing the button was “done” flawlessly.
Also:
Update the requirements document with every change and communicate this clearly to your programmers.
Another example:
I want a button on my landing page that leads to my affilate offer versus a redirect page.
Bad:
Make a green button, leading to redirect.
Better:
Put a green button on the lower page, leading to redirect.php
Better still:
Put a green button on the lower page, just before the footer.
Clicking the button will lead to redirect.php.
Best:
– At the end of the text container, put a green button. The button should be labeled “Claim your prize NOW!”. The color code for the button is #00FF00. See attached screenshot of layout (layout_mockup_01.jpg).
– When the user clicks the button, he is directed to redirect.php in the same directory. The link opens in the same window.
– Please contact me with any questions.
Drawbacks to this method
I am tempted to say “NONE” but of course there are.
You will be spending more time on your requirements and you will still mess it up sometimes. Live and learn.
Advantages of this method
Your coders will know exactly what is required of them, leading to them being more productive and feeling more secure in what they are doing.
You will get better results and the chance to dispute badly done work.
Join me for more fun in part 3 -Tracking features and bugs
::emp::
This is perhaps a bit off topic, but the best requirements are executable tests (I’m a programmer by trade). Example:
$browser->go( “http://www.example.com/” );
assert( $browser->text_matches( “click( “Claim your prize NOW!” );
assert( $browser->location() == “redirect.php” );
…It is “more expensive” to write your requirements that way, but the results are correspondingly more valuable. Take a look at selenium or similar for examples.
–Robert
This is a great idea, if not for two caveats:
1: Not all people doing outsourcing are programmers by trade.
2: Not everything can be put in a codable test (layout, design, etc..)
But a good idea if yu are talking about code to be developed and if you have the means to write unit tests.
::emp::
[…] 1 – Introduction and Description of the problem Part 2 – Requirements and you Part 3 – Tracking Features and Bugs Part 4 – The little black book that could Part 5 – Your […]
I think one thing you were pointing out here was that there are a difference between Functional Requirements and Non-Functional Requirements. The former are those that have a strict yes/no whether they have been successful or not. The latter are things like “Should be visually appealing to attract bees.”
For functional requirements it is important to answer how you’ll determine whether that requirement was met or not. This should all be in the SRS (Software Requirements Specification) document.
Hi Whiner.
Well yes, in project management speak, this distinction is often made.
I did not distinguish between functional and non-functional requirements in the article, because the point I was trying to make “Your requirement is the cornerstone in evaluating the work done and should be created with the utmost care.” Holds true for both.
Non-functional requirements, such as design will be the hardest to describe as “met goal” or “did not meet goal”, and as such very hard to outsource.
Either find a designer you are comfortable working with, or try defining the work process instead. I.e. define how many revisions should be done, how many versions to start with, etc…
Giving examples is also a good idea when dealing with design “Should look similar to XYZ” can be done, but of course limits creativity.
All in all, I think giving design work away to cheap labor overseas is even more difficult than outsourcing development.
::emp::
Great series emp
[…] 1 – Introduction and Description of the problem Part 2 – Requirements and you Part 3 – Tracking Features and Bugs Part 4 – The little black book that could Part 5 – Your […]
Really, there is very little difference between your “bad” requirement and your “best” requirement IF YOU ALSO INCLUDE THE LAYOUT MOCKUP. The only additional information you have provided in the “best” requirement example is “the link opens in the same window”.
I would argue that your “best” requirement example contains too much low-level information that is either obvious from the mockup, or which should be abstracted into a separate look-and-feel requirement that lists the standard colours that are used for each design element on the site.
Your “print button” story is a perfect example of the poor quality of software developer working for a lowest-cost outsourcing company. A good developer would know to ask some more questions if a requirement was so obviously incomplete.
Cheers,
Stuart.
Well, yes.
But the entire idea was that the “bad” reqirement did not have a layout mockup, color information and the like.
If you would include that, it would make it a “good” requirement.
As for the programmer asking questions, etc..
I really think this is a failure of the model, and not a question of whether or not the programmer is good or not.
Even a good programmer will only do the minimum work required, as the current outsourcing model will often not pay for clarification of requirements.
All I am promoting here, really, is good communication. I can not heal the current outsourcing model.
The problem with hiring programmers is they will do exactly what you ask them to do.