Forem: John Franey

How to write user stories that actually get done

John Franey — Sun, 07 Dec 2025 15:51:56 +0000

Introduction

At each stop in my career, I seem to develop a reputation for being a Fussy Franey with user stories.
I've seen some eye rolls when I've asked for one story to be broken into three, and I've faced incredulity when pointing out that one "user story" is actually an entire epic---or even so broad in scope that it could be an entirely separate business.

I like to get things done, and I've found that small, well-written user stories are the single biggest enabler of dev velocity.

User stories should be small

Very small.
How small?

They should encompass a single user interaction, single visual element, or single application reaction.

Reducing scope for a feature or launch should not require rewriting user stories

What counts as a user interaction?

Viewing something, like a list of contacts
Navigating to a page
Entering a value in a form field
Submitting a form
- This doesn't include form submission accoutrements, like showing a loading icon (separate story), showing an error message (separate story), or showing a success message (separate story)

What counts as a visual element?

Viewing is an action, and seeing a visual/UI element counts as a user story.
Visual elements can be tiny, too, like a red notification dot you might see on a new menu link.

It might seem like overkill to have an entire user story for a notification dot, but the menu item can exist without the notification dot.
Because the notification dot depends on the menu item, it can be implemented separately from the menu item and prioritized separately, too.

What counts as an application reaction?

An application reaction is a change in the application that happens as a result of a user action or as a result of other application logic.
The reaction could take place within an application (a toast notification) or across applications (sending an SMS).

Some quick examples:

Validating an input
Showing a toast
Showing a loading element
Showing a logout warning
Sending a confirmation email

Q: When is a story not a story?

A: When it's an epic!

For example, let's take the following story:

As a user, I can delete a to-do item

Sounds like a small, regular story, right?
Not so fast.

A story like that could have a number of requirements before it could be considered done (optional requirements marked with asterisks):

Showing a confirmation modal when clicking the delete button*
Writing the API delete endpoint
Performing the API delete request on click
Disabling the button while the request is processing*
Removing the to-do item on a success response
Showing a success toast*

There's a lot happening there.
There's enough happening here to make deleting a to-do item an epic rather than a single story.

And what's an epic?
An epic is "a large, high-level piece of work" (ScrumAlliance) that consists of multiple user stories and other pieces of work, like non-user-facing dev tasks.

Atlassian has a helpful explanation of epics as a strategy to break down work into smaller pieces:

Epics are a helpful way to organize your work and to create a hierarchy. The idea is to break work down into shippable pieces so that large projects can actually get done and you can continue to ship value to your customers on a regular basis. Epics help teams break their work down, while continuing to work towards a bigger goal. (Atlassian, "Agile epics: definition, examples, and templates")

In other words, an epic captures an entire feature flow, like the end-to-end (and frontend-to-backend) process of creating a to-do item, and it consists of one or more user stories and/or dev tasks.

Note:
"Managing" something should never be a single user story.
If your user story starts, "As a user, I can manage...", it's likely a project, and each of the Create, Read, Update, and Delete actions may well be its own epic.

Can stories have multiple acceptance criteria?

They can!

But they still need to be small, and the acceptance criteria need to be so intimately related that separating them would be impossible to implement or impossible to verify.
So what is a story that can have multiple acceptance criteria?
The second requirement in the epic above is a good example:

As a user, I can confirm whether I want to delete a to-do item

This story might have acceptance criteria like the following:

GIVEN I am a user viewing a to-do item

WHEN I click the delete button

THEN I am shown a confirmation modal
GIVEN I am a user confirming whether to delete a to-do item

WHEN I click the close button on the confirmation modal

THEN the modal is closed AND the to-do item is not deleted
GIVEN I am a user viewing the delete to-do confirmation modal

WHEN I confirm my intent to delete the to-do item

THEN the item is deleted AND the modal is closed

Showing a confirmation modal (application reaction) when clicking the delete button (user action) encompasses two UI elements and one action+reaction, but still makes sense to have in the same user story because there's no way to validate that the delete button behaves as expected without having a confirmation modal to view.

The story could be broken into subtasks to parallelize development by creating a subtask for the design of the confirmation modal.
Ideally, the confirmation modal would be reusable and wouldn't have to be implemented separately for each action.
For more on this, see the "User stories should be new" section below.

Note:
Multiple user stories can be coded in a single branch and merged in a single pull request.
For example, showing a success message on a successful form submission and showing an error message on an unsuccessful one could make sense to code together.
They are different enough that they should be in separate user stories, though, because one could be done without doing the other.

User stories should be explicit

A story's definition of "done" should be unambiguous.

Acceptance criteria should be specific and comprehensive, and it should be described in writing rather than being hidden in designs.

If a story involves changing text, for example, include the old and new text in the acceptance criteria.
When acceptance criteria read something like "Update wording to match designs", changes are easy to miss, which can throw off estimates and lead to QA rejections.

Info:
Gherkin syntax (GIVEN/WHEN/THEN) is helpful to describe a story's scope.
If a story is difficult to describe in the GIVEN/WHEN/THEN format, it's also going to be difficult to code, review, and QA.

User stories should be new

Existing capabilities can be acceptance criteria, while new capabilities should be user stories.

If you have a form component that shows an error message on a 500 response, for example, there doesn't need to be a new user story to use this behaviour in a new form.
For another example, if you have a phone number field and you want to see a phone number input on a mobile device, because this is a built-in capability of an <input type="tel">, it doesn't need to be its own user story.

Info:
Subtle changes to existing behaviour should be captured in a separate ticket.
It's a good idea to have one or more developers audit acceptance criteria to identify new features that may be masquerading as acceptance criteria.

Lightning summary ⚡

While it may seem tedious to have stories with such a narrow scope, large user stories often mask complexity in a project, posing challenges to estimating, sequencing, QAing, and descoping work.

User stories that actually get done are small, explicit, and new.

AWS documentation frustrations

John Franey — Mon, 04 Sep 2023 14:25:14 +0000

Introduction

AWS has a ton of documentation, and sometimes it misses the mark.
Recently, I came across two different examples of AWS documentation either perplexing or frustrating me.

Note:
By "frustrating", I mostly mean it in the "hinder or prevent (the efforts, plans, or desires) of" meaning of the word (WordWeb).
Mostly.

Now, I don't want to come across as a complainy Franey, but since I've been working on documentation for Blurry, a static site generator I open-sourced (and that builds this site), I've been thinking about what makes good technical documentation good.
I don't think I've figured it out quite yet, but I have found two traits of AWS docs that can hurt documentation, and maybe doing the opposite can improve it.

Read on for a break-down of two AWS documentation breakdowns and what I learned therefrom.

Trait 1: perplexing

How many steps does it take to get a direct link to the VS Code extension?

From the Lambda function console page, it took 4 clicks, reading, and scrolling to get to the actual VS Code extension.
Even from the AWS Toolkit for Visual Studio Code site, it was still two clicks to get to the page with the direct VS Code link (and that link was below-the-fold).

That's quite a long walk for what ended up being a link that opened the extension in VS Code itself.
Four clicks for something that could be one click?
That's pretty perplexing.

There's some risk in having that much documentation about a VS Code extension, too.
Having a documentation site separate from the README could mean:

You have to maintain documentation in multiple places, which can be difficult to keep in sync
If documentation in one of the two places isn't unique enough to have to keep in sync, that means the docs may be general enough to be not that helpful

Info: I do need to give credit where it's due: an earlier version of the VS Code extension documentation didn't have a link that opened the extension in VS Code; after all that clicking, it asked that we open VS Code and search for the extension.

Trait 2: frustrating

It's frustrating when documentation is incomplete---especially in code examples.

Take this Python code sample for AWS CDK's PythonFunction, for instance:

entry = "/path/to/function"
image = DockerImage.from_build(entry)

python.PythonFunction(self, "function",
    entry=entry,
    runtime=Runtime.PYTHON_3_8,
    bundling=python.BundlingOptions(
        build_args={"PIP_INDEX_URL": "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL": "https://your.extra-index.url/simple/"}
    )
)

Linting the code using Pylint via (Pyrfecter), we can see a number of linting issues:

2:9: undefined name 'DockerImage'
4:1: undefined name 'python'
4:23: undefined name 'self'
6:13: undefined name 'Runtime'
7:14: undefined name 'python'

There are a couple missing imports that were easy to sort out (Runtime, DockerImage), but python?
I couldn't find that in the CDK Developer Guide or the CDK API documentation or the AWS CDK Examples.

After getting help from a search engine, I found that the missing python import is:

from aws_cdk import aws_lambda_python_alpha as python

And the PyPI package to install is:

aws-cdk-aws-lambda-python-alpha

And self?
The python.PythonFunction call shoud be inside a CDK Stack.

If we check the documentation for that, we get an example of an App and a Construct, but the Stack classes are stubbed:

from aws_cdk import App, Stack
from constructs import Construct

# imagine these stacks declare a bunch of related resources
class ControlPlane(Stack): pass
class DataPlane(Stack): pass
class Monitoring(Stack): pass

class MyService(Construct):

  def __init__(self, scope: Construct, id: str, *, prod=False):

    super().__init__(scope, id)

    # we might use the prod argument to change how the service is configured
    ControlPlane(self, "cp")
    DataPlane(self, "data")
    Monitoring(self, "mon")

app = App();
MyService(app, "beta")
MyService(app, "prod", prod=True)

app.synth()

There are no linting errors, at least!

For a code example of a Stack, I went to the documentation for App and found this:

class MyFirstStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs):
        super().__init__(scope, id, **kwargs)

        s3.Bucket(self, "MyFirstBucket")

And the linting output?

1:20: undefined name 'Stack'
3:31: undefined name 'Construct'
6:9: undefined name 's3'

We can get the Stack and Construct imports from the code sample in the Stacks page.

So.
After checking the the aws_cdk.aws_lambda_python_alpha API docs, multiple pages of the AWS CDK Developers Guide, the GitHub examples repo, and some searching to find the docs for "@aws-cdk/aws-lambda-python-alpha module" (which is separate from the CDK API docs), we have enough documentation to use these new (and very helpful!) Python CDK constructs.

But, boy, did I have to work for it.
I can't remember how much time it took for me to get a complete working example, and I shudder to think of how many dev-hours have been spent in a similar pursuit.

A complete, working code example would save oodles of time, and I'm happy to oblige:

from aws_cdk import Duration, RemovalPolicy, Stack
from aws_cdk import aws_dynamodb as dynamodb
from aws_cdk import aws_lambda as lambda_
from aws_cdk import aws_lambda_event_sources as event_sources
from aws_cdk import aws_lambda_python_alpha as lambda_python
from aws_cdk.aws_lambda_python_alpha import PythonFunction
from constructs import Construct


class WorkingStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Resources
        python_dependencies_layer = lambda_python.PythonLayerVersion(
            self,
            "PoetryLayer",
            entry="./src/layer",
            compatible_runtimes=[lambda_.Runtime.PYTHON_3_10],
        )

        dynamodb_table: dynamodb.Table = dynamodb.Table(
            self,
            "WorkingTable",
            partition_key=dynamodb.Attribute(
                name="PK", type=dynamodb.AttributeType.STRING
            ),
            stream=dynamodb.StreamViewType.NEW_IMAGE,
            sort_key=dynamodb.Attribute(name="SK", type=dynamodb.AttributeType.STRING),
            removal_policy=RemovalPolicy.RETAIN,
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
        )

        # Functions
        react_to_new_entries_function: PythonFunction = PythonFunction(
            self,
            "ReactToNewEntries",
            entry="./src/functions",
            index="react_to_new_entries.py",
            runtime=lambda_.Runtime.PYTHON_3_10,
            layers=[python_dependencies_layer],
            environment={
                "TABLE_NAME": dynamodb_table.table_name,
            },
            timeout=Duration.seconds(29),
        )

        # Event handling
        react_to_new_entries_function.add_event_source(
            event_sources.DynamoEventSource(
                dynamodb_table,
                starting_position=lambda_.StartingPosition.TRIM_HORIZON,
                batch_size=5,
                bisect_batch_on_error=True,
                retry_attempts=1,
            )
        )

        dynamodb_table.grant_read_write_data(react_to_new_entries_function)

Info:
I'm working on another post showing a complete AWS CDK project with typed Python.
Stay tuned!

Summary

Documentation should yield more answers than questions

If your documentation requires multiple other (possibly unlinked) documentation sources to be helpful, there's a problem.
Code samples, especially, should be complete, to make it easy to get started using your code.

Info: Maintaining complete and accurate code samples can be hard to maintain and verify, which is one of the reasons I once made flake8-markdown, a little package to run flake8 on Python code blocks embedded in Markdown files.

(I should probably be using it on johnfraney.ca, now that I think of it.)

Documentation should anticipate the information a reader is most likely looking for and make that easy to find

If someone clicks a link about a VS Code extension, make the call-to-action to download that extension dead-simple to find.
Additional information can be helpful, too, especially for someone learning a new skill or concept, but make it easy for someone who has a good idea what they're looking for.

Last rites writes words

Writing documentation is hard.
And it's easy to pick on AWS, not only because they have so much documentation, but also because they have the resources to maintain great docs.

But reading documentation is much easier than writing it, and complaining about documentation is much easier than fixing it.
So keep an eye out for things that make documentation great and grody, send up PRs, and write some code...y.

Show: Responsive Image Generator - multiple WEBPs and responsive HTML from a single image

John Franey — Sun, 26 Mar 2023 22:33:49 +0000

Hello! Today I made public a little tool I've been working on that makes it easy to add a responsive image to your website.

It uses Imagemagick via Web Assembly to generate multiple resized & converted-to-WEBP images from a single image you upload.

The styling might leave a fair bit to be desired, but I wanted to get this into the world as soon as it worked. I hope someone finds it useful!

https://johnfraney.ca/tools/responsive-image-generator/