What does it take to change a text label?

In software development, we’re often asked to produce estimates of how long a task would take. At the beginning of our careers, many things may seem relatively easy. But as we gain experience, we understand that even simple requirements may take more time than one would expect.

Let’s take the simple example of updating a text label. Recently, my team decided to change a word in the user interface. It used to be “Transactions”, but we now think that “Cash Flow” is more representative.

Simple Requirement: Change the text on the tab

Fifteen years ago, I would’ve said that this is such a simple change that should take no more than a few minutes. Today, however, I look at it differently. As a senior software engineer, I look for answers to the following questions:

• Where is this text defined? We’ve probably used the same word in many places. How do we identify which of them relate to this particular instance?
• Is the text defined uniquely for this instance? In other words, is it possible that changing the value for this instance affects other instances where the same text is used? How will we verify that the change only affects the desired places?
• Is the text defined in multiple places, such as a server-rendered view as well as a client-side view? Or perhaps an HTML view and a PDF? Or web and mobile apps?
• Are there other places in the UI where we should change the text so that our UI is consistent?
• Is the text context-dependent? What if a filter is applied, such as a date range in the future? Does the text become “Estimated Cash Flow”, for example? Should all users see the same words, or do they have different meanings for different user roles?
• Are there other dependent pieces of text that need to be updated as well, such as tooltips, contextual help, or in-app tutorials?
• What about translation and internationalization (i18n)? If we have to ask an external entity for the right translations, how long is this going to take? What if the translation is five words instead of two? How would it affect our UI/UX?
• Does the new text affect our UX? For example, is the new text, or some translations of it, too long to fit our existing maximum tab width? Or is it long enough to push other tabs out of visibility, or cause them to wrap on multiple lines? How does it look on smaller screens? How do we test this? Do we have automated tests that can capture such issues, or do we have to check it manually on different devices?
• Having changed the text, should we change the semantics around it? For example, should we change the HTML element id? If we do, then would it affect data binding or CSS paths, or impact our SEO? Would it affect navigation links?
• Having changed the text and potentially the element id, what impact does this have on our automated test suite? Would it break some tests that were matching against the text, or using the id to look up child elements? How does it affect in-app tutorials?
• If we’ve changed the id, should we now change the API to reflect the new entity name? If we don’t, then it’s harder to trace the UI back to our server-side logic. But if we do, then we need to think about all the questions that we need to ask when changing an API. (That topic deserves another article.)
• Is the old text mentioned in our docs or training materials? Do we have a way to trace where mentions of a general word such as “transactions” relate to this particular instance that we’re changing? Or will we have to scour through every page in our documentation where the word is referenced?
• Is the old text shown in screenshots in our docs or marketing materials? Do we have a way to trace those screenshots, or do we have to hunt them?
• Will we be deploying this change to all of our users at once, or does it need to be configured via feature flags?
• How will we inform our users of this change? Could some of our customers be puzzled when they don’t find the familiar “transactions”? Should we inform our customer support team to expect questions around this topic? Should we add a new entry to our FAQ?
• Will the change cause backwards-compatibility issues for our customers, such as broken bookmarks or bookmarklets?
• Will the change affect external dependencies that our customers use, such as web scrapers, Greasemonkey/Tampermonkey scripts, custom stylesheets, or embedding our content?
• How will we measure our customers’ satisfaction with our new choice of wording?

So many considerations for a seemingly simple task!

As you can see, even a simple user-facing change requires much thought to do it properly. If customer satisfaction is high on your priority list, then you need to apply this kind of thoroughness to your process.

In my opinion, the main job of a “senior” software engineer is to raise these questions. It may not be too hard to answer them, but it takes a lot of expertise to know which questions to ask.

Let’s rephrase the original question: What does it take to apply this change with high quality? Of course, it depends on the answers to the questions above. But it also depends on how much you’ve invested in the right form of automation, tooling, and process streamlining. A good process with the right tooling gives us quick and precise answers to our questions and enables us to move quickly with confidence.

Note that automation is not a goal in itself, but rather a means to an end. You could have a huge test suite that checks every piece of text in your UI, but it may not be helpful. If every change you make causes many tests to fail, you’ll be inclined to change the tests so that they pass. But then, what good is a test that gets changed every time your code changes? How do you capture incorrect changes? That’s why I emphasize the right form of automation and tooling.

I often get into conversations about whether quality is directly proportional to the time and effort required. In other words, does focusing on quality necessarily make you slower? In my opinion, high quality requires a substantial short-term investment in the right form of automation, tooling, and process streamlining. In the short-term, like any investment, it makes us slower. However, the return on investment (ROI) can be huge. In the medium to long-term, this kind of built-in quality can make you faster by orders of magnitude.

As a contractor, I often start new engagements where my managers are hoping for a quick turnaround of new projects. I try to clarify that I may not make your deliverables faster in the short-term, but I will definitely try to help make you faster in the long-term.

If you’re looking for a senior, polyglot software engineer that applies this kind of thoroughness to his deliverables, or if you think you could use a short-term consultation on how to improve your status quo, feel free to drop me a line.

Thanks for reading. I hope you’ve enjoyed it! I appreciate all kinds of feedback, so kindly let me know your thoughts in the comments.