Beta Acid

Wow! That design process was a doozy. But you've made it! Time to kick off development! But… Now what? How do you translate your cutting edge and beautiful designs into concrete tasks for your development team?

Here at Beta Acid, we specialize in doing this very thing. Here are some helpful tips on how we approach writing User Stories for front-end development. This approach can be used for all types of front-end projects including responsive web apps, native mobile apps, etc.

Tips Before Starting

1. We don't care about any fancy methodologies or frameworks (gherkin is only a type of cucumber to us). The point is communication so use whatever works best for your team.
2. Designs are never final so don't assume that they are. Designs tend to continue to evolve even after they are approved. Select an approved version and use that as a reference for your story. Plan for adopting changes through an iterative development process.
3. Don't assume that something is "standard" and will be built by default. Unless explicitly documented, you risk the chance of something being missed.

Purpose of User Stories

The purpose of a well written User Story is to communicate design and product requirements for the piece of functionality the Engineers are building. It should be the single source of truth for Engineering during the development process.

User Stories should break down designs into bite-sized pieces of development that can be tackled by a single engineer. If it is helpful for your team, you may also want to consider limiting User Stories to, at most, one day of development time for a single engineer. This prevents User Stories from getting too large/complex which could impact both development and QA.

User stories are also heavily used by Quality Assurance teams. A well written User Story can be used as a checklist of what to test and how to test it. It sets expectations with your QA team and helps to ensure a smooth and efficient QA process.

Who Should Write User Stories

Anyone with adequate knowledge of the product and design requirements can write User Stories for development. It is typically the responsibility of a Product Owner or Product Manager. However, writing User Stories can also be completed by a Project Manager or Engineer with the proper knowledge and background.

Key Elements of a Well Written User Story

Screenshot of the screen from your designs

You can also supplement the screenshot with a link to the full design file. However, providing only a link to the design is not recommended. A screenshot draws a line in the sand of what the engineering team will build. When the designs change (and they will), there will be a misalignment between the written User Story and the design file. You also lose the history of what design was used to write the User Story. With a screenshot of the designs in your User Stories, you create a single source of truth for what is to be built and retain history which will reduce the risk of a confused Engineering team.

Content and Functionality

For simple screens or features, look at the screen designs from top to bottom. As you're scanning the screen, write down everything that you see and what it does. It is important to be as explicit, detailed, and prescriptive as possible. In conjunction with the design screenshot, the developer should have everything they need within the User Story to understand exactly how the screen should appear, what functionality it should have, and exactly what happens when the user interacts with any part of the screen. For more complex features, use the same process as above but it may be appropriate to break the features down into smaller stories.

Don't forget about:

• User States. Does the functionality or screen change based on the User's status, role, or other attribute? For example, the User is logged in vs. logged out, the User is an administrator, the User has completed a particular task, etc.
• Validation. What information should be validated or checked? If the information is incorrect, what should happen? Consider complex validation scenarios as well; does one field depend on another?
• Loading States. What does the screen, its contents, or CTAs look like when loading occurs?
• Empty States. Is there a situation where a list of data or other information may not be present? If so, how should the screen handle it?
• Hover States. If the user hovers over a component with their mouse, what should happen?
• Error States. What should happen when an error occurs?
• Analytics. What analytics should be captured on the screen?
• Keyboard Types. For mobile apps, if a keyboard pops up for an input field, what sort of keyboard should be displayed? Should it have a "Return", "Next", or "Go" button? Should it be restricted or are all characters allowed?
• Animations. Does something on the screen automatically move? If so, describe exactly how it should move. Or, include the animation file that should be used for development.

An Example

Below is a real-life example of a story we wrote for the Login Screen of a mobile app build.

Header

"Back" CTA to the left. When tapped the user should get to the previous onboarding screen. ABC Company logo on the right. When tapped, the user is directed to the Home screen.

Screen Contents

Screen will show a "Login" title. A text input field with the title "Username"

• When the user taps into the field, the default keyboard should appear.
• On the default keyboard "returnKeyType" should be "next". When tapped the user will lose focus of this field and focus will move to the next field "Password". A text input field with the title "Password"
• When the user taps into the field, the default keyboard should appear.
• On the default keyboard "returnKeyType" should be "done". When tapped the user will lose focus of this field and the keyboard disappears.
• Password text input field will be obfuscated by default and show an open Eye Icon.
• If the user taps the open Eye Icon - Change to a closed Eye Icon - Display the password as plain text (not obfuscated)
• If the user taps on the closed Eye Icon - Change to an open Eye Icon - Obfuscate the password

A "Sign In" primary CTA

• The CTA is always in an active state
• When tapped it will make a call to the Login endpoint and the loading indicator will appear.
• Client side validation: - If the user taps "Sign in" but the username and/or password text input fields are empty. - Display error messages under each empty field: - Username: "Please enter a username" - Password: "Please enter a password". - Each empty field will appear outlined in red.
• Endpoint responses:
  • [URL or relative path of the endpoint - removed for confidentiality]
  • 200 response
    • if (mfa_setup_required = true) navigate to MFA screen
    • else: store the 'token' in secure storage and navigate to the dashboard screen.
  • 400 response
    • Display 'message' value from response

Footer

• "Privacy Policy" CTA at the bottom right side of the screen.
• When a user taps on it, they will be able to see the Privacy Policy, shown in an in-app browser.

Analytics

• Record a Page View event
• Field validation errors for username and password fields
• Tapping the "Sign In" CTA

Pro Tips

Use Component Names

If you are using a design library or design system, use the actual name of a component in your User Story. This will ensure that the correct component is used.

Capture All Error States

Work with your Engineering team to get a list of all errors that can occur on a particular screen. Make sure your User Story documents all possible errors in order to ensure that every scenario is handled gracefully.

Order your Epics for Development

The order in which you tackled the design process may not translate well for development. Have a chat with your development team to sequence your Epics for development in the most logical way possible. Often, the first three epics are:

• Design library and common components: build it once then reuse them over and over again. It will speed up the rest of development.
• Global navigation: so you have a way to navigate through your app to different areas of functionality
• User creation and authentication: in many apps, you can't do much else if you don't have a user to do it with.
• After that, it really depends on your product so rely on your engineering team for guidance.

Timing of Back-end Development

The following discussion of team sequencing probably deserves an entire article of its own. Where possible, we try to keep the back-end team two epics ahead of the front end team; sometimes this means doing back-end work while designs are still in progress. This allows the front-end team to hit the ground running as soon as designs are approved.

Yes, you can use mock endpoints in a pinch but this approach adds two phases of work to your schedule: building mock endpoints and re-testing against real endpoints when they're ready. It also often causes a bunch of re-work if your API contracts are not solid (thus your real endpoints end up being different from the mock endpoints you built).

Is it worth it?

A well written User Story does take (a lot of) time. Sometimes, especially for very small, close knit teams that have worked together in the past with solid relationships between product, design, and engineering, the level of detail in a well written User Story is not worth the amount of time they take to write. However, there are many scenarios where well written User Stories are highly valuable. A couple scenarios are: Large teams where there might not be very much communication between a product owner or designer and the engineers,

Teams where new engineers are being onboarded mid-project and lack historical or domain knowledge. In these cases, a well written story is your go-to tool to communicate requirements so the detail is crucial. Evaluate where your team is on this spectrum and adjust accordingly.

Conclusion

This is how we do things at Beta Acid, but it's not a one-size-fits-all solution. We believe adaptability and flexibility is critically important. For every project we evaluate how to be as effective as possible given the variety of client and team needs. Sometimes, a well written User Story creates efficiencies that far outweigh the time commitment to write them.

Want to learn more about working with us? Reach out to: hi@betaacid.co.