Lately I’ve been thinking about the risks associated with:

• moving content
• refactoring domain terms within content.

I’ve identified the key areas of risk as narrative and permalinks.

Narrative

The narrative of your site/app can break in subtle and unexpected ways. It is difficult to guard against side-effects upon the narrative. This makes changes to domain terms high-risk. Specifically, a developer focused on the code can easily miss these side effects.

Here’s an obvious, and well guarded story:

Given I am a user
When I visit the user's profile
Then I see their latest activity

That one’s simple, if you move the latest activity to a sub-nav, this story will break (that’s a good thing). In this case, you could ask the product owner, “In the past, having a user’s activity visible on their profile page was desirable. Are you sure you want to lose that?”.

However not all narrative is this cut and dry. Consider this story:

As a user
When I visit a member's profile
I can see a list of pages the member is interested in.

Then, along comes a new unit of work, “Rename all pages to interests”. This seems reasonable, and so you finish the story. The test for the ‘pages’ the member is interested in continues to work, however the member profile ought to lose any reference to ‘pages’. The new domain term ‘interests’ should be used instead.

Now your tests are using misleading or confusing language. You need to update all your stories to use the new term. This can get onerous quickly, but it’s vital for consistency.

I’m yet to find a satisfying technique for mitigating this risk. It’s hard enough keeping the modelling clear of inconsistencies.

This same change to narrative also affects ‘curators’ of ‘pages’. They no longer curate ‘pages’, they now provide ‘interests’. Do we want the curators to go through this mental hurdle, or the strangeness of ‘managing an interest’ versus ‘my interests’? Suddenly a curator has a list of ‘interests which they maintain’ and a list of things they are ‘interested in’.

The best way to mitigate the ‘broken narrative’ risk is to stay strong on short, testable stories. Fast turnaround between development and acceptance is also valuable. The fast feedback cycle is less overwhelming for both developer and product. The chance to think about risks is stronger when the story is as uncomplicated as possible.

The risk of broken narrative is just another reason to avoid this internal desire to take ‘big bites’.

Permalinks

Permalinks and long lasting links, are any URLs for which permanence matters. E.g., the permalink to an article on your blog from some outside source. The risk of broken permalinks can be readily mitigated in your intrgration tests. To achieve this, you need to make sure that product is thinking actively about permalinking. Impart to the product owner that permalinks must be (as much as is possible) explicitly called out in stories.

Permalinks in cucumber tests

Here is an example.

A story in your backlog calls for content that must be available in a permalink. You write a scenario like this:

Given I am a visitor
And there is an article
When I click on a permalink for the article
Then I should see the article

The important term in this story is ‘permalink’ – whenever a step definition calls for a permalink, it needs to use a constructed link:

visit ('/articles/#(article.slug}')

Do not use Rail’s (or your framework of choice) magic:

visit(article_url(article)) # won't capture intent

This way, if the permalink goes away, the test fails, and the intent is clearly captured.

 The many unseen dependencies

To complicate matters, a moderately complex site usually has a swathe of references to the content you are about to move/refactor. The term is often used in abundance, E.g. ‘Post’ or ‘Job’ or ‘Activity’. The page might be accessed from several places, E.g. messages are available from the ‘User -> Messages’ nav item, the ‘”My Favorite Lolcats” group messages’ page etc..

Key take-aways:

• Fast feedback loops. (small testable and deliverable chunks of work)
• Oodles (lots) of product owner/ux designer/copywriter/developer collaboration.
• Changes in domain terms need to be kept consistent throughout your tests.