Best Practices: Appian User Stories

Heuristics of Complex User Stories

While scoping, prioritizing and designing user stories for the Appian platform, pay close attention to the technical design and implementation of user stories exhibiting the following heuristics.

Appian recommends for the implementation teams to review their designs and approaches with Appian lead designers or Appian architects

User Story Heuristics

Risks

Import or export of data from/to a file like Excel, CSV, flat file, etc...

Storing/caching large amounts of text data in the Appian engines.

Heap memory usage on application server.

Query more data than what is needed to be shown to the end user

Heap memory usage on application server.

Long running database query affecting UX and scalability.

Multi-step workflow assigned to the same user

Abuse of the activity chaining feature.

Application server threads "locked" to activity chains.

Application server scalability.

ETL-type user stories: data is transformed using complex logic without user interaction

Application server and engine server resource usage.

Overall impacts on performances.

Complex business logic and processing in process models

Large process models are difficult to develop and maintain.

Unattended and headless user stories

Hard to predict system load.

Potential impacts on user driven activities that compete for resources.

Functional use cases stretching over weeks/months

Long running Appian process instances.

Unscalable application design.

Complex and resource intensive process-to-process communication.

Process centric design

Long running Appian process instances.

Unscalable application design.

Complex and resource intensive process-to-process communication.

JMS inbound/outbound integration 

Not supported on Appian Cloud.

Email inbound integration

Fragile integration patterns.

Appian to Appian integration

Siloed applications/platforms.

Complex data dictionary and data model

Complex nested CDTs difficult to create and maintain.

JPA cascading refresh and update issues.

Complex logic in process to work with nested CDTs.

Document generation

Storing/caching large amounts of text data in the Appian engines.

Resource intensive text manipulation.

Large volume of process instances, nodes (PM size or MNI), users, documents, data, etc...

Large resource usage.

Scalability of the solution.

Internationalization

Can add overhead and complexity depending on the use case.

“Hacking” the product

Using unsupported APIs, functions, etc. or leveraging features in a way that weren’t intended.

Not always supported by Appian Support and subject to product changes.

Event-driven architectures

Generally high-volume use cases that can lead to scaling issues if not implemented correctly.

Complex integrations

Non-modern, high-volume, and high-load integrations, or integrations with non-standard authentication methods.

Scalability of the solution, resource usage, response time, and/or security.

User Story Design Template

Use the template below to plan the design for your user story, brainstorm test cases, and gain a shared understanding with your team. This document should be reviewed by the team after the story has been groomed, but prior to beginning development. Following this template is a recommendation; however, the template can be modified as needed to fit project needs.

While there is some additional upfront cost associated with creating design documents for user stories this approach, teams have reported the following benefits:

  • In-depth technical analysis prior to story development
  • Increased understanding between designer and peer reviewer 
  • Fewer missed acceptance criteria 
  • Reduced number of bugs pushed to higher environments
  • Decreased effort spent fixing bugs 

It may be helpful to denote in-progress or completed items with formatting (for example, highlight all steps which are in progress). Any italicized text in the template can be removed. For easy tracking in JIRA, it is generally recommended that this design document be created as a subtask of the parent story to link its progress to the overall work. Upon creation, the task is assigned to a reviewer or discussed with the team prior to close-out.

View an example design document to see how this template can be used. 

[Link to Story] Story Name

To be completed by the developer:

Design

Provide a design for the functionality needed for the user story, which may include the data model changes, integrations, interface, or process model changes. Include database definitions, pictures, or mockups where necessary.

High Level Summary:

Detailed Notes:

Unit Testing

Prior to development, identify valuable test scenarios not explicitly stated in the AC. These should be informed by the story design and the risks it will introduce. Scenarios should be reviewed and added to by the team before development starts to get fuller test coverage on areas of risk.

Note: For more standard test cases that are described in the AC, the developer can generally refer to the ACs or copy them with slight modifications for clarity, rather than spending time re-writing the AC in a different format.

To be completed by the peer reviewer:

Peer Review

Depending on your project, you may choose to put this information in Jira, or whichever ticket tracking tool your team uses. 

  • Code Review Feedback:
    • Indicate any feedback for the original developer here per your team’s peer review and UI checklist.
  • Peer Testing:
    • Indicate any test scenarios you are going to cover. Different formats may work for different teams (e.g. Excel), but the idea is to track what has been tested and what remains. If documenting these test cases is not beneficial to the team, this section can be removed.
  • Bugs:
    • Indicate any bugs you have found related to this story and whether they have been fixed. All bugs should be fixed and tested before a peer review can be considered complete.

User Story Estimation

Similar to how some projects use hours to estimate level of effort, story points are a relative measure of effort that encompasses size, complexity, and uncertainty. Agile projects use relative estimation to convey the level of effort needed to complete a user story.

Story Point Basics

  • Quick, relative estimates - Story points are quick, relative estimates that are obtained by comparing stories to other work. They take into account the size, complexity, and uncertainty contained in developing and testing a story.
  • Unit-less - Story points are unit-less so they do not provide a false sense of accuracy like hour estimates can. For example, it is very difficult to estimate the exact height of the Empire State Building in meters; in contrast, it is much easier to estimate the height of the Empire State Building in comparison to nearby buildings.
  • Relative to entire team - Story points provide development teams with varied skill sets a shared unit to compare complexity relative to a set baseline. Hour estimates are relative to a single developer’s skill set, creating an uneven playing field for estimates.

Setting Expectations

Story points are estimates; they are not meant to be exact measures of time or complexity, but rather are an approximation of complexity, effort, and uncertainty. Estimates are subject to change, just as scope and requirements may change.

Estimation Techniques & Tips

Stories should be estimated by the development team by comparing to a baseline, a simple story whose point value is agreed upon by the entire team and is referenced throughout sizing. Before estimating, the team should select several representative baseline stories. For example, a baseline story could be creating a form with three input fields and is considered 2 points by all team members.

Other tips for sizing stories include:

  • Estimate based on complexity, not time
    • Do not try to translate points into hours. This defeats the purpose of relative estimation and makes the points dependent on a single developer’s skillset.
  • Set an upper point limit
    • For example: Stories should not be higher than 13 points.
    • Break stories that exceed this limit into smaller pieces. Smaller stories are easier to estimate, as unknowns and complexity cannot always be measured and do not scale.
  • Agree on a scale
    • Fibonacci series is commonly used for user stories (ex: 1, 2, 3, 5, 8, 13...).
    • Most stories should be within about one order of magnitude (ex. from 1-10).
    • T-shirt sizing is popular for epics or projects and are good for high level discussion.
  • Play Planning Poker
    • If the story is pretty well understood (e.g. contains clear acceptance criteria) planning poker is a good technique for group estimation.
    • Involve the entire delivery team in planning poker to get a well-rounded view of the story (functional, development, testing).
    • Each player individually estimates the story, then the team shares at the same time to avoid anchoring and group think.
    • Estimate quickly - no more than 1 to 3 minutes per story.
    • Move to the next story if consensus is reached; otherwise discuss and re-estimate. If there is still not consensus after 3 rounds, set the story aside to discuss at a later time and move on to the next story.
    • Use planning poker cards, mobile applications (iOS and Android), or online tools.
  • Try Affinity Estimation
    • When there is a large number of stories without a lot of detail, Affinity Estimation is a an option for coming to quick, high level, initial estimates.
    • See this blog post for more details.

Estimating Velocity

Velocity is the number of story points a team can complete in a given sprint. Velocity is used to identify a team’s rate of progress and scope out the release plan and future sprints. Future velocity should be adjusted based on historical performance of the team.

When estimating a team’s initial velocity, it is crucial to remove any undue optimism in order to account for distractions, meetings, and aggressive estimates. This is typically accomplished by lowering the velocity by a small number of points or adding a buffer story. It is common for new teams to take a few sprints to determine their true velocity.