Writing Complete Stories - NCIOCPL/cgov-digital-platform GitHub Wiki

A story ticket is more than just the initial “As a __ , I want to __ , so I can __” statement. It encompasses the details of the change, acceptance criteria, approach, and tasks.

A complete story ticket should cover aspects of front end views across breakpoints, back end fields and properties, translations, and analytics.

Process of Creating Stories

The story ticket should come together over time, and be a collaboration between all team members.

The first draft of the story itself (As a [role], I want [feature], so that [benefit]) is the starting place.

First discussions should determine:

  • If the story is accurate, and the right size/scope (Should several be combined? Should one be broken down into several smaller ones?)
  • A general idea as to how to approach achieving the goal of the story.

Based on the new stories and the approaches, then the change details can be spelled out.

Depending on how confident we are in how the story will be approached, the Acceptance Criteria may also be drafted. But since the implications of changes are easier to overlook in the ACs, and incorrect ACs can cause confusion later, it may be a good idea to wait to write them.

The story ticket will also change over time. The full ticket should be reviewed by all team members for accuracy and clarity before it goes in the backlog. It also should be reviewed and adapted when it's pulled into the current sprint.

Elements to Consider

Front End

The front end includes the overall page display at every breakpoint, as well as what content elements are being displayed.

Elements to consider:

  • Which back end fields are being displayed
  • Changes at each breakpoint
    • Which fields are pulled, image position/display, background changes, styling changes
  • Fallback content for optional fields (Is another field pulled, or is the display blank?)
  • Multiple templates for the same item (for example, images can be displayed inline at multiple sizes)
  • Accessibility elements in the code (alt text, long descriptions)

There will also be elements of translations to consider

Documenting display properties

The details and acceptance criteria can mention styles, but specific style elements like hex codes and pixel layouts should live in separate documentation to ensure consistency.

If an InVision comp has styles defined, the inspector mode can be used to get display details.

Back End

Back end changes can be either new elements, or changes to existing ones.

Elements to consider:

  • Where the new field/updated field should appear
    • Can be just what appears above/below
  • Specifics of the Drupal field properties
    • Field name
    • Type of field
    • if it’s required
    • Don’t forget tooltips!

Drupal field properties should be updated on the Wiki as well as the stories.

Example Drupal Field Properties

  • Field Name: actual name in Drupal (check with Dev)
  • Label: Title of field in CMS
  • Type: Plain text, WYSIWYG (simple, streamlined, full), dropdown (specify options below), upload
  • Required: Yes/No
  • Max characters: Depends on type
  • Max file size: For uploads only
  • Permitted Types: For uploads only
  • Tooltip Text: Tooltip that appears in CMS
  • Cardinality: 1 (if a single choice ), or * (if infinite choices)
  • Translatable: Yes/No - will a user be able to change this on a translation of the page?
  • Note: Any elements that change from standard presentation of the type (Upload field without alt text, for example)

A note about tooltips

Tooltips around upload fields are a mix of customizable text and automatically generated specs. Generally the part that specifies file quantity, size, and type are automatic. Because of differences between production and the various development environments, the max size of the upload may change.

Analytics

Elements to consider:

  • New click events
  • Click events that are changing location
  • existing analytics that will apply to new elements

Make sure to specify which analytics properties are new and which already exist but apply to the situation.

Translations

Translations may have front and back-end implications.

Elements to consider:

  • Which fields are able to be translated
  • Which fields will be displayed from the Spanish version of the content type
  • What happens if a translation is not available (For example, if a translated page has a feature card to content that hasn’t been translated)
  • Any fallback fields that might be different than the English version

Structure of the Story Git Ticket

The ticket title should be a summary of the issue.

  • Story: As a [role], I want [feature], so that [benefit]
  • Change Details
  • Acceptance Criteria
  • Resources
  • Notes
  • Solutions - Prerequisites, Tasks, Technical Notes
## As a [role], I want [feature], so that [benefit]

> **ESTIMATE** 20

### Change Details

#### Front End Changes
1. 
2.

#### Back End Changes
1.
2.

#### Other Changes
1.
2.

### Acceptance Criteria

​```gherkin
Scenario: [title]
  Given [context]
    And [some more context]
  When  [event]
  Then  [outcome]
    And [another outcome]
    
    ### Resources:

* Feature: JIRA Ticket #
* Mockups: *Here goes a URL to or the name of the mockup(s) in inVision*
* Web Page: *Here goes a URL to an existing web page*

### Notes

*Some complementary notes if necessary:*

* > Here goes a quote from an email

* Here goes whatever useful information can exist…

---

## Solution

### Prerequisites

- *required dependency for identifying the problem, scope and then solution for this issue*
  Short Spike Description - Issue #9999

### Tasks

Short Task Description - Issue #9999
Short Task Description - Issue #9999

### Technical Notes

- More notes, or technical nuances/direction

Change Details

The change details section should spell out the changes that need to be made. This will help define the scope of the work to be done, and can be used as overview for development and testing.

Change details can be broken down into Front End, Back End, and Other (often analytics, but could also have content implications).

Examples:

Back End

  1. Adding a new paragraph type to the contents options for the Home and Landing page

Front End

See comp for specific style details

  1. Title of the new block is H3, light blue, and has no hove

Difference between change details and acceptance criteria: The acceptance criteria might include elements that are staying the same, but the details should focus on changes, and specs of new elements.

Acceptance Criteria

Acceptance criteria writes out the nitty gritty details of how the changes will appear and function. It's written as a series of when-then statements in Gherkin, which allows our Quality Assessment (QA) team to check that things are working as expected.

Some of the testing will be done manually. Other elements of testing can be automated.

A note about Gherkin: The QA team will almost certainly modify the wording in the Gherkin definitions, since they are approaching every story from a perspective to make its steps reusable and optimized for automation purposes.

Common Scenarios for Acceptance Criteria

Changes by breakpoint
  • Specify the screen size as part of the “given”
Scenario: View infographic on a mobile device – no mobile optimized version
  Given The user is using a device with a screen at 768px or smaller
Checking for code
  • Write from user perspective
  • can have “user views page source” as the “when”
Scenario: User wants to view alt text of inline infographic - has text
Given the user is viewing the desktop version infographic on a page at any template
	And the infographic has “Test alt text” in the Alt text field of the desktop file upload
When the user views the page source “alt text=“Test alt text”" appears in the source code for the image

Scenario: User wants to view accessible text -  has text (for testing)
  Given the user is viewing the infographic on a page
 	 And the infographic has content in the Accessible Text (longdesc) field 
  When the user views the  page source “img longdesc” attribute appears in the source code 
  Then the “img longdesc” attribute points to a URL that contains the media ID (e.g. /media/923228/long-description)
Looking at translation
  • Add a “background” before the scenario that states language setting
Background
  Given that language is set to “ES”

Utilities

DS Story

DoR Tasks

  • Comps Created
  • Comps Reviewed using Checklist
    • Developer Review
    • IA Review
    • Product Review
  • Comps Approved
    • Developer Approval
    • IA Approval
    • Product Approval
  • Scenarios Created
  • Scenarios Reviewed
    • Designer Review
    • Developer Review
    • IA Review
  • Scenarios Approved
    • Designer Approval
    • Developer Approval
    • IA Approval
  • Acceptance Criteria Drafted
  • Acceptance Criteria Reviewed
    • Developer Review
    • IA Review
  • Acceptance Criteria Approved
    • Developer Approval
    • IA Approval

DoD Tasks

  • Governance Drafted
  • PR Review (see PR for review and comments)
  • Client review with demo

Digital Platform Ticket

DoR Tasks

  • Content Model Drafted
  • Images attached to ticket (Design)
  • Content Model Reviewed
    • Developer Review
    • IA Review
  • Content Model Approved
    • Developer Approval
    • IA Approval
  • Acceptance Criteria Drafted
    • Analytics Acceptance Criteria Drafted (As applicable)
  • Scenarios created for YAML
  • Acceptance Criteria Reviewed
    • Developer Review
    • IA Review
  • Acceptance Criteria Approved
    • Developer Approval
    • IA Approval

DoD Tasks

  • Governance Drafted
  • PR Review (see PR for review and comments)
  • Client Review with Demo