I need to explain the needs for integration of a web-based service on our website to the programmers. I want to find out the best structure for such a request.
How should I describe the features I want from a non-technical point of view?
Add a comment
|
4 Answers
TL;DR
You should not be defining tasks for technical people. Instead, you should describe a value proposition and some testable acceptance criteria, and then turn your technical experts loose to find a solution that delivers the defined value you're looking for.
User Stories Describe Value
User stories are a good vehicle for defining value. Using the standard Connextra format of "role, feature, reason" is a good starting point. For example:
As a banking client
I want to be able to view a list of recent transactions
so that I can reconcile my checkbook.
The role (or "value consumer") defines the intended audience of the feature. The feature itself describes what the feature should do, and the reason provides some context about why the user may want the feature.
The feature is described in terms of outcomes, rather than specifying the underlying technical implementation. Constraining the implementation is generally a bad idea. Instead, you define a business or UX objective and allow the technical team to find the best way to meet it.
The reason (or "context") is also very important. Using the example above, there are lots of ways to display a set of transactions. However, by describing a specific use case (e.g. reconciling a checkbook), you are providing guidance to the team that can help them select the best technical implementation to meet the objective from among the available options.
Make Sure It's Testable!
The most important thing one can do, whether using user stories or specifications, is to ensure that the objectives are presented in a way that's testable. If it's not testable, it's hard to reach a genuine understanding between the business and the technical team.
Using the example story above, one might use the output of the feature to reconcile a sample checkbook. You and the technical team might define an account for John Doe as follows:
- John starts with $100.
- The recent transactions should add up to $60 in checks.
- John should then have $40 left.
This can then be verified using manual or automated tests. If the test passes, then the feature has been successfully delivered, and can even be refined further in the future. If the tests fail, then obviously a working solution is still needed.
"How to Fail" in Two Easy Lessons
Vague Stories
Compare the advice about good user stories to a vague user story such as:
As anyone at all
I want to see a pretty list of transactions
using an attractive font.
This sort of story is entirely subjective, and can't be tested. Who will use this feature? What's "pretty?" Which font will be considered attractive? Neither the technical team nor the business can succeed with hand-waving criteria like this.
Over-Specification
On the other hand, over-specification isn't your friend either. Consider this example:
As user 321
I want to see exactly 10 checking transactions displayed
in a sans serif 6 point font named "Obscure Sans."
This type of specification is probably testable, but overly constrains the solution. The implemented solution might only apply to a single user, who must be specified using a numeric ID. It fails to address all the possible edge cases (e.g. what happens if user 321 only has 6 transactions in total?), and forces a technical implementation such as a specific font choice that may or may not work in all browsers, or even be readable at the specified font size.
At Least Fail in a Testable Way
Both vague stories and over-specified stories are likely to lead to misfeatures or outright bugs. However, if you have to err, at least err on the side of testability!
answered Aug 28, 2016 at 2:53
Stories should always be defined in business terms. Why does there need to be web integration? Who is it for? What exactly does it need to accomplish?
If it is not directly-related to a business requirement (unlikely for web integration, but theoretically possible), then it should instead be a developer task, and thus it should be defined by a developer.
Developers define developer tasks. Non-developers define business stories - if more technical details need to be filled in, then the developers can do that themselves. This should, ideally, be done in collaboration with someone who understands the business aspect, so as to quickly catch misunderstandings regarding what the story is supposed to actually accomplish.
Imagine you are going to the hospital and meeting with a doctor to help you because you have chest pain. Do you tell the dr straight away "I have a heart problem, i just read webmd, I need a heart transplant, schedule it for tomorrow"? Obviously, I'm sure you could understand why a dr might grin in this circumstance.
What you usually do is say "I have a pain in my chest, it started an hour ago". The dr might ask "what did you eat for lunch"?. They might take a blood test or run an EKG. They may conclude you just have acid reflux.
My point is... An "integration" is a solution. Not a problem. Explain the problem. Technical people are put off when non technical people approach them with solutions. Non technical people tend to only accidentally stumble on good technical solutions if ever (emphasis on the non technical). Yes, occasionally there are very savvy people who are the exception... But it's best to play dumb and let the technical people arrive there themselves. They've had too many run ins with the norm that teach them otherwise.
Mostly agree with @codegnome and just summing up and adding my 2 cents
- Describe features in terms of stories (it's often a good way to convey information that you could ignore as for you are trivial giving your background)
- Try to transform the Story in terms of Interfaces and desired Input and Output through them, implementation details should be out of this scope.
- Testing: define what you are going to test and how you are going to test it. Developers will then be able to create code that passes the tests (TDD) and that's consistent with the story
