documenting behavior.md

For a bit of important background, read about using narrative to explicitly define behavior.

Below is an example of documenting a feature's behavior. Feel free to edit this page for clarity, this process and documentation are always evolving. To get started with your own feature once you're familiar with this, use some feature description boilerplate

Comments and descriptions will be in callouts like this, they aren't a part of the sample feature description, but are there to help explain what is being documented, how, and why.

---

Incoming Calls

The feature name. Features are the highest level of granularity for a product. User Accounts, or Vehicles are features, usually they will be a simple noun, and be one of a handful of things with which users will interact. This also helps clarify explicitly what won't be a part of the product (yet).

Feature Description

The high-level description of what this feature is. This is ideally discovered early on in the business development process and only identifies user contexts, highest level behavior description, and the motivation for needing that behavior. Will probably have only a few Connextra formatted narratives.

As a Receptionist
I want to quickly log an incoming call
So that I can get back to answering more calls and the sales team can handle the call

As a Sales Manager
I want to see the status of incoming calls as they happen
So that I can make sure they are handled by my team

As a Salesperson
I want to indicate whether any phone call I recieve relates to a lead
So that my Sales Manager has the information he needs

---

Feature Behavior

The rest of the feature description document is detailed description of behaviors that define the feature. They will mostly use Gherkin formatted narrative as the goal is to explicitly defining behavior is a systematic way. This format will feel burdensome at first, just remember that the goal is to have as little structure and formatting as is necessary, but remain systematic and explicit. It's a balancing act that will take some practice and evolve. Don't be afraid to play around with the formatting!

Context

A quick description (if necessary) for what environment or previous events necessitated the use of this feature.

A call comes in that is related to sales, and thus transferred to a an extension to be answered by a Salesperson.

Behavior

Given I am a receptionist:

  When I am on my dashboard page
  Then I see a box to put in the extension I tranferred the call to
  And A dropdown to select the dealership with all dealerships present
  And my current dealership is selected
  And I see a dropdown to select the Salesperson receiving the call
  And 'first responder' is selected

  When I type in an extension
  And click "Dispatch"
  Then I see a flash message saying "Call dispatched"
  And the form is reset

Given I am a Salesperson:

  When I'm on my dashboard page
  And I just finished taking a call for me on line 201
  Then I see a list called "Calls"
  And I see an item in that list for the call on line 201
  And I see that it is assigned to me (or available)
  And I see how long ago that call came in

Given I am a Sales Manager:

  When I look at my dashboard
  And a call just came in on line 201
  And it hasn't been "handled" yet
  Then I see a call on line 201 in the "Calls" list
  And I see the salesperson's name (if assigned)
  And I see how long ago the call came in

  When the call has been handled by a Salesperson
  Then I still see a call on line 201 in the "Calls" list
  But it is a full row with information about how it was handled
  And I see an "x" button to dismiss that call

  When I click the "dismiss" button
  Then the call item disappears from all Sales Manager's "Calls" lists
  And the record for this call is permanently deleted

Scenario 1: A call doesn't relate to a lead

Scenarios are simply ways to group associated behaviors together. They make the documentation more consumable, and make finding specific behaviors later easier. A good scenario title implicitly starts with 'When'. ("When a call doesn't relate to a lead...")

Given I'm a Salesperson:

  When I click the "Trash this call" link
  Then I have the option to submit a short description of why I trashed the lead
  And that call disappears from all salespeople's "Calls" lists

Given I'm a Sales Manager:

  When a call is transhed by a Salesperson
  Then I see the name of the salesperson
  And I see that they trashed the call
  And I see the reason why they trashed if they entered one
  And I see how long ago they trashed the call
  And I can click the 'dismiss' button

  When I click the "x" button on the call
  Then I am prompted to ensure I know this will remove the call from salespeople's screens
  And the call is permanently delete
  And the call is removed from all salespeople's "Calls" lists

Scenario 2: A call is a new lead

Given I'm a Salesperson:

  When I click the "+" link on a call item in my "Calls" list
  Then the new lead modal appears
  And the lead source is be preselected as "Phone"
  And I cannot change the lead source
  And the extension is be prefilled with the call's extension
  And I cannot change the call's extension

  When I fill in the new lead modal and click "Create"
  Then that call disappears from all salespeople's "Calls" lists

Given I'm a Sales Manager:

  When a lead is created from a handled call
  Then I see the name of the salesperson
  And I see the description of the lead that was created as a link
  And I see how long ago the lead was created
  And I can click the "dismiss" button

Scenario 3: A call relates to an existing lead

Given I'm a Salesperson:

  When I click the "arrow" link
  I see a list of my currently active or sleeping leads
  When I click an item in that list
  And I click the "Add" button
  Then that call disappears from all salespeople's "Calls" lists
  And I am on the selected lead's page

Given I'm a Sales Manager:

  When an existing lead is asociated to a call
  Then I see the name of the salesperson
  And the description of the lead that was add to as a link
  And I see how long ago the call was associated with the lead
  And I can click the "dismiss" button

---

Future Iterations

It's best to only document behaviors that exist or are part of the next product iteration for a lot of reasons. The 'Future Iterations' section is a good place to keep behaviors that we think of but that weren't ready to be a part of the product, or put behaviors that get cut from the current iteration that we want to implement later.

  Given I am a Sales Manager
  When a call was completed
  Then I see how long it took from creation to completion on the list item