The document provides guidance on writing requirements to define a software project from concept to coding. It discusses establishing the client's needs through defining the territory, context and direction. It also covers identifying users and writing personas, user stories and acceptance tests to define features and their scope. The goal is to fully specify requirements before development through documenting the user stories, workflows, wireframes and specifications for each feature. This process aims to uncover gaps and ensure all parties share a common understanding of the project.

1. From Concept to Coding
THE ART OF WRITING REQUIREMENTS

2. The Beginning: Oh, the noise!
Oh, the Noise! Noise! Noise!
That's one thing he hated! The
NOISE! NOISE! NOISE!
~ The Grinch
PATHFINDER
DEVELOPMENT
© 2008
The beginning of a project generates a lot of great ideas; BUT, until a structure or cohesion is applied to these ideas, they end
up being a loose collection of separate ideas with no direction. (And weʼve all worked on THOSE kinds of projects before.)
Requirements brings cohesion and direction to the noise.

3. Requirements: Establish the territory;
establish the context;
establish the direction
PATHFINDER
DEVELOPMENT
© 2008
Because we are consultants, when we start new projects we like to know the clientʼs territory, context and direction. Territory is
the space the client occupies - their vertical; context is the clientʼs role within that territory - what service to they provide;
direction is where the client needs to go - does the project support this

4. Product Requirements
defines product concept and user base
PATHFINDER
DEVELOPMENT
© 2008

5. From Problem to Solution
Client: Sustainable Developer
Works with communities and planners
★
Promotes emerging technology
★
• wind farms, sustainable housing, etc.
PATHFINDER
DEVELOPMENT
© 2008
Hereʼs our imaginary client: a Sustainable Developer. Their territory is construction/development; the context is that they bring
green ideas to traditional planning/building.

6. Business Problem: no one
gets our ideas until theyʼre
built -- and then itʼs too late.
PATHFINDER
DEVELOPMENT
© 2008
If you canʼt articulate the problem, how can you define a solution?

7. Product Concept: We need an interactive
tool to visually explain our ideas in order to
get usersʼ input and buy-in
PATHFINDER
DEVELOPMENT
© 2008
The product concept addresses the problem; it is the overarching idea of your software and all features need to relate back to
it. Defining the concept is the first step in restraining scope creep.

8. Identify the Users
Who will be using this software
Research who will be using your product
★
Identify the Personas
★
PATHFINDER
DEVELOPMENT
© 2008
Identifying users allows you to create a product that meets their needs, instead of a product that meets what it thinks the
needs of the users are. Addressing the actual needs of the people who will be using your product puts you further ahead on
the road to success.

9. Personas: Personas are
fictitious characters created
to represent the different
user types that might use a
site or product.
PATHFINDER
DEVELOPMENT
© 2008
Personas are effective in keeping meetings focused on the product and the users who will be directly interacting with it.
Addressing any issues from the POV of a persona removes the personal from resolving fringe case arguments or the latest
widget advocates; i.e., stating it makes no sense to Persona Sally is an effective argument since she is the end user of the
product

10. Who are the Personas for this
Product: We need an interactive tool
to visually explain our concepts in
order to get usersʼ input and buy-in
PATHFINDER
DEVELOPMENT
© 2008
hereʼs the concept again -- research into the types of users interacting with this product will yield personas

11. city council
the community
fellow visionaries
PATHFINDER
DEVELOPMENT
© 2008
For our case study, weʼll say our research uncovered users who can be categorized into these groups:
city council
fellow visionaries
the community

12. Identify Usersʼ Goals
What do they need to accomplish; what
are their goals
High level User Stories describe needs and goals
★
As a user, I need to do a task so I can accomplish my goal
★
PATHFINDER
DEVELOPMENT
© 2008
Personas have needs and goals. User stories help us to transform these needs and goals into user requirements. These
requirements will, in turn, define what it is weʼre building.

13. As a member of the Community, I need to:
Search for developments in my area
★
so that I can stay current
View the proposed solutions so that I
★
can become informed
Be able to add my comments so that
★
my voice is present
View a list of meeting times so that I
★
can plan to participate
Receive alerts so that I can be
★
updated
PATHFINDER
DEVELOPMENT
© 2008
User Story: As a user, I need to do something in order to get this benefit.

14. User Needs > Features > Scope
Personasʼ definition helps to determine:
Tasks the system must support for user to meet their
★
goals
• add an account
• manage that account
Which tasks to consolidate into features
★
• Adding an account and managing that account means at a high level
weʼll need an Account area in the application
Features & tasks determine the scope and effort
★
PATHFINDER
DEVELOPMENT
© 2008

15. Concept + Users + Tasks = List of Features
PATHFINDER
DEVELOPMENT
© 2008
The list of features is what youʼll need to begin to scope out a project. Writing user stories for the features helps to nail down
scope and determine the needed effort by development. Ranking the features helps with the iteration planning.

16. Feature Requirements
define the scope and functionality
PATHFINDER
DEVELOPMENT
© 2008

17. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the acceptance tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008
At Pathfinder, weʼve found documenting these five attributes are sufficient to fully define a feature. Starting at the highest level
(user story), we drill down into the details, uncovering gaps or discrepancies before weʼve started coding. Design before
development saves money and time.

18. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the acceptance tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008
At Pathfinder, weʼve found documenting these five attributes are sufficient to fully define a feature. Starting at the highest level
(user story), we drill down into the details, uncovering gaps or discrepancies before weʼve started coding. Design before
development saves money and time.

19. User Story: States the
functionality of a feature as
told from the POV of the
Persona. Describes the
what, not the how.
PATHFINDER
DEVELOPMENT
© 2008
User Stories are very high level and are used to estimate the degree of difficulty to implement (which ties in with iteration
planning)
Use cases are a sequence of steps detailing the interactions between an actor and the system and are generally used to
capture the functional requirements of a system before implementation.

20. Characteristics of a good
User Story - who, what, why
A user story is written at a high level
★ Tells you who is using the feature
★ Describes what a user can do with this
feature, not how theyʼll do it
★ States the featureʼs benefit for the user
Used to generate the acceptance tests
PATHFINDER
DEVELOPMENT
© 2008
The syntax we use for User Stories is:
User Story: As a [persona - who], I want [feature - what], so I can [benefit - why].

21. User Stories - Where to Start?
Identify the tasks a user needs to do in a
feature
I need to create/update/delete accounts
★
Write the user stories based on those
tasks, but at a high level
I need to manage accounts
★
The acceptance tests will get into more
detail
PATHFINDER
DEVELOPMENT
© 2008
The syntax we use for User Stories is:
User Story: As a [persona - who], I want [feature - what], so I can [benefit - why].

22. User Story: As a [persona - who], I
want [feature - what], so I can
[benefit - why].
PATHFINDER
DEVELOPMENT
© 2008

23. User Story: As a Community member, I
want to find planning meetings, so I can
participate in the process.
PATHFINDER
DEVELOPMENT
© 2008

24. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the acceptance tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008

25. Acceptance Test: series of
scenarios based on the User
Story that defines the
scope of the feature along
with its acceptance criteria.
PATHFINDER
DEVELOPMENT
© 2008
Describe the feature such that everyone – the business people, the analyst, the developer and the tester – have a common
understanding of the scope of the work and agree to a common definition of “done”.

26. Characteristics of a good
Acceptance Test
Acceptance Tests have more detail than
a User Story but less than the
development specifications
Two parts:
Title describes an activity that the user wants to do in
★
this feature
Scenario is described in terms of Givens, Events and
★
Outcomes
PATHFINDER
DEVELOPMENT
© 2008
Acceptance tests are the next level down in details from the User Stories. They are scoping out the feature and defining what
complete means for that feature. While they are written in more detail than a user story, itʼs still more along the lines of a
scenario rather than specifications.

27. Givens, Events, Outcomes
Scenarios:
Precondition (the givens)
★
Actions (the events)
★
Expected Behavior (the outcome)
★
PATHFINDER
DEVELOPMENT
© 2008
The givens should define all of, and no more than, the required context
The event should describe the actions the user takes
Outcome describes the desired behavior of the actions

28. Title
Given that [context]
And that [some more context]
When [event/action]
And [additional actions]
Then [expected outcome]
And [additional expected outcome]
PATHFINDER
DEVELOPMENT
© 2008

29. Search for Events
Given that the user is a member of the
community
And that the user has successfully
logged in
When the user enters search criteria for
an event
And the user specifies a location
Then the systems returns all events for
that location that match the search
criteria
PATHFINDER
DEVELOPMENT
© 2008

30. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the acceptance tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008

31. Workflow: diagrams a
sequence of steps from start
to finish that a user takes in
order to complete a feature.
PATHFINDER
DEVELOPMENT
© 2008

32. Workflow Diagrams
The end-to-end flow visualizes the big
picture
Identifies the starting point(s)
★
Notes any decision point(s)
★
Shows any subpaths a user can take
★
Declares the End Point
★
PATHFINDER
DEVELOPMENT
© 2008

33. Workflow Language
start page action decision?
process end
PATHFINDER
DEVELOPMENT
© 2008
Regardless of the language you use, be consistent in your diagrams and differentiate between the different actions in a flow.
Also, know your audience -- in the US and other Western cultures we read left to right, top to bottom. Therefore, construct
your flows in such a way that they flow naturally for your readers.

34. Workflow Diagrams
Illustrate a Userʼs Path through the Feature
★ Highlight Start Point(s)
★ Identify Decision Point(s)
★ Show where the flow ends
PATHFINDER
DEVELOPMENT
© 2008
A good diagram will show all the entry points, the decisions and their results, and any branches available to the user. The flow
will also show the end point. They help team members create the user experience, both at the UI layer and the backend
workflow.

35. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the Acceptance Tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008

36. Wireframes: a visual guide
used to suggest the layout of
the fundamental elements in
the interface.
PATHFINDER
DEVELOPMENT
© 2008
Because a picture is worth 1,000 words.

37. Wireframes
Provides a visual reference for the
structure of a page and placement of
elements
Establishes the language, content and
structure of user interaction
PATHFINDER
DEVELOPMENT
© 2008

38. What does a Wireframe look like?
PATHFINDER
DEVELOPMENT
© 2008
wireframes can run from pencil sketches to whiteboard drawings to layouts using a vector-based graphic program to high-
fidelity. The type of wireframe you use is the one appropriate to the state of your project and to the feature you need to convey.

39. PATHFINDER
DEVELOPMENT
© 2008
wireframes can run from pencil sketches to whiteboard drawings to layouts using a vector-based graphic program to high-
fidelity. The type of wireframe you use is the one appropriate to the state of your project and to the feature you need to convey.

40. PATHFINDER
DEVELOPMENT
© 2008
wireframes can run from pencil sketches to whiteboard drawings to layouts using a vector-based graphic program to high-
fidelity. The type of wireframe you use is the one appropriate to the state of your project and to the feature you need to convey.

41. PATHFINDER
DEVELOPMENT
© 2008
wireframes can run from pencil sketches to whiteboard drawings to layouts using a vector-based graphic program to high-
fidelity. The type of wireframe you use is the one appropriate to the state of your project and to the feature you need to convey.

42. PATHFINDER
DEVELOPMENT
© 2008
wireframes can run from pencil sketches to whiteboard drawings to layouts using a vector-based graphic program to high-
fidelity. The type of wireframe you use is the one appropriate to the state of your project and to the feature you need to convey.

43. PATHFINDER
DEVELOPMENT
© 2008
Since it is the conversation around the drawing, and not the drawing my itself, that is of interest, wireframes can capture that
conversation by notating the user interactions.

44. Anatomy of a Feature
Requirement
For each Feature:
Identify the user stories
★
Write the Acceptance Tests
★
Diagram the workflow
★
Create the wireframes
★
Write the specifications
★
PATHFINDER
DEVELOPMENT
© 2008

45. Specifications: document
the details and behavior of a
feature, explaining the
content and actions so that
developers can start coding.
PATHFINDER
DEVELOPMENT
© 2008

46. Specifications Describe:
Elements that should appear on a page
How the user interacts with a page
What happens when the user does
something
PATHFINDER
DEVELOPMENT
© 2008
write in plain english -- not developer speak or consultant speak

47. Specifications
Search Events
Search criteria - at least one is required:
★
• date - standard text field with calendar widget
• location - pulldown of locations in the system
• sponsor - pulldown of city aldermen showing FirstName LastName
Search validation
★
• date format is valid - MMMDDYYY
• at least one field has data
On Submit
If errors:
★
• cancel submit
• highlight fields with errors (if no fields contain data, show message that
at least one field must contain data)
• display error message: Please correct the error before continuing
If no errors:
★
• Display search results on the Events List Page
PATHFINDER
DEVELOPMENT
© 2008

48. for more information, contact:
Paul Dittmann
pdittmann@pathf.com | 312.372.1058 x6006