We have an internal tool where our account management teams can say "whenever we send this type of SMS message, use this text I specify instead of the default text". They would call this 'configuring a custom SMS'.

Minimum viable info about how our SMS-sending code works -- the API takes a message name and a user to send it to. First we fetch the 'SMS Rule' for this message name, which contains information about what the message's content should be. If no rule exists, we create a rule with the default settings. Then we use the 'SMS Rule' we retrieved to send the message.

The internal tool works by persisting an 'SMS Rule' for the message name. So, when we're sending the message, we pick up that user-created 'SMS Rule', accomplishing the effect.

So my problem is: how should our internal UI refer to the action of 'specifying an SMS to be sent'?

If it's 'configuring a custom SMS', we now have a split in the company where two teams use different words to refer to the same thing. This has already happened in other areas and I sometimes feel like I have to "code switch" when talking to Engineering vs. when talking to our account management team. Particularly with the new engineers, I have to teach them several names for the same concept, which feels wrong.

If it's 'creating an SMS Rule', this is pretty unintelligible for our account management team. I could try to educate them about the concept, but it has no relevance to them -- they just want to specify SMSes to be sent to programs, why do 'Rules' have to be involved?

When I try to answer this question myself, I come up with "well, it's OK if they have different names because they're conceptually different things, although they happen to be implemented the same way." I find this somewhat convincing, but it also rings hollow because there's little chance the "configure a custom SMS" feature will not be implemented using SMS Rules in the future.

It seems like you're assuming the only option is to keep the UI and code terminology different, or change the UI to match the code. Can't you change the code to match the UI? Seems like that could be as simple as using the word 'Configuration' instead of 'Rule' in the codebase.
– bdslJul 29 '18 at 11:40

Suppose you want "SMS rule" because it makes sense and it covers the meaning. Just refactor your code base throughout to use that name and use it yourself whenever the subject is talked about, internally and externally. If a stakeholder uses another name you put on your puzzled face, take a meaningful pause and say "Oh.. you mean rule!" and proceed without further ado. It is not something they care about, it is something you have to work with. You could make a note in the code that says "PM calls this configuration" and leave it there. The bottom line: it has to make sense to code maintainers.
– Martin MaatJul 30 '18 at 5:32

What is wrong with calling it a Custom SMS internally?
– immibisJul 31 '18 at 5:13

3 Answers
3

What you're describing seems to equate to the concept of Ubiquitous Language (see Martin Fowler's brief writing and the C2 wiki page on the subject) from Domain-Driven Design. If you were to follow the ideas of ubiquitous language, you would carry the domain language from your users through the entire system, from the requirements to the user interface and into the code base.

Ubiquitous language facilitates communication between stakeholders and developers on a few levels. Consider your user interface - your application becomes more intuitive if the terminology used matches the user's domain language. Consider enhancement requests or bug reports - stakeholders will likely use their domain language, so if your code and documentation matches that, you will be more easily able to identify the components of the system that are likely to be affected by the changes to provide the enhancement request or bug fix.

You can call things (in your UI, in your code base, in your documentation, in your sales and marketing material) whatever you want. However, there are very good reasons to (1) stay consistent throughout and (2) use the domain language whenever possible.

I've had cases again and again over the years where the domain language changed. And where people changed the code accordingly, but missed half of it, so two different names were used in code. Until the domain language was changed again, resulting in three different names.
– gnasher729Jul 28 '18 at 23:39

4

@gnasher729 DDD recognizes that the domain language will grow and change over time. Managing those changes in the code base needs to be treated like any other refactoring. Or not changing (or an incomplete refactoring) needs to be treated as technical debt - something that will slow the team down and make it harder to evolve the software.
– Thomas Owens♦Jul 28 '18 at 23:43

@ThomasOwens Thanks for the link. Which of the two options would you recommend taking? (Or would you propose a third?)
– Eli RoseJul 29 '18 at 2:04

@Eli Rose What two options? I didn't present any options. The names and terms used should be consistent throughout your system.
– Thomas Owens♦Jul 29 '18 at 10:07

@ThomasOwens I think Eli is asking about the two bullet points in the question.
– bdslJul 29 '18 at 11:41

In general, it should, but user-visible names are subject to change at very late stage of development, due to non-technical reasons, and by that time may bee to late tl get rid of the older name everywhere, so they stay different.

It definitely helps to do so. However, you can choose to not do so if you can justify the benefit from not doing so. I know it's a vague answer, but it's the most precise you can get without making contextual evaluations (including company priorities).

As a simple (well...) example, I worked on the social security platform for the local government. As you may suspect, the legislature and business requirements are built on decades of agreed upon names. Many systems have been in place for more than one generation of developers, so the names have become ubiquitous.

For reference, we speak Dutch in this region, not English.

Software is written in English, even if everyone involved speaks Dutch. It's a matter of good practice. But what do we do with the customer-specific-jargon? Some examples:

I doubt many people can accurately express the exact legal differences between "civilian" and "citizen". Dutch has a similar distinction ("inwoner" and "burger"), but even translation dictionaries conflate the meanings (since the dictionaries are not written from a strictly legal context).

If we translate the codebase and use English terms, then we're bound to run into problems. Some developers will put the wrong word into code. Some developers may mistranslate the code when they speak to the client (thus getting back negative feedback that seems like they wrote wrong code, but they really just used the wrong word to describe the intention of the code.

On the other hand, if we don't translate, it doesn't matter. The developers don't care about the particular word that is used (they could in theory use Foo and Bar and be happy with it), as long as it's used consistently.

There is a particular legal right that is given to citizens. Its literal translation is "citizen's right". Citizens have many rights, but this one in particular is called "citizen's right".

If we translate the code base, what do we call this specific right? Its literal name is too confusing in English. Inventing a new name is counterintuitive and will lead new developers needing a dictionary to map the codebase to the analysis.

Even though it breaks the "no mixed language code rule", choosing to not translate domain concept is the better choice here. At the cost of breaking a theoretical rule, it maintains consistent definitions between all involved parties, it helps contextualize the intention of code (as most developers, as citizens, are aware of social security concepts and their intentions).

What's more important here is that we chose the naming that benefits the developers. Our choice was made specifically to make development of the application easier by simplifying client-developer communication (on a topic that's already incredibly complex).

If it's 'creating an SMS Rule', this is pretty unintelligible for our account management team.

This is often where the functional analyst or project owner comes into play. They are usually the translator between client and developer.

If the clients and developers are speaking different languages, get someone to translate on either party's behalf.

If it's 'configuring a custom SMS', we now have a split in the company where two teams use different words to refer to the same thing.

I see your point, but you can't prevent the fact that different words have different meanings in different contexts. That's just how languages work.

For example, "integrate" has completely different meaning to a software developer, a mathematician, or a social worker. That doesn't mean we should all decide to not use the word in the future.
In a way, if you avoid using a word that makes sense to you, simply because someone else has used this word in a different context, then you are creating a "dependency" on the other person's jargon. Ideally, you write your code (which includes naming) without considering non-developers.

I think it's a general professional tip that you always take care to talk to someone while being aware of the context in which they understand you. The same applies here. Understand that the other party understands these words differently, and then avoid ambiguity in communication.

"well, it's OK if they have different names because they're conceptually different things, although they happen to be implemented the same way."

There are many cases where I see this happen, and the decision is often to not try to unify for the sake of unification.

A Book, Author and Planet may all have a string Name property, but that doesn't mean we need to abstract it into a shared concept (e.g. IHasName).

A Planet may have PlanetSize and PlanetType properties, both of which are structurally the same class (int ID; string Name;), but that doesn't mean they need to derive from the same base class (e.g, ObjectWithIdAndName).

In short: Just because two concepts have a similarity does not mean that is is a shared/common similarity. Maybe it just happens to be similar, without there being an actual connection.

So my problem is: how should our internal UI refer to the action of 'specifying an SMS to be sent'?

If you have two equivalent synonyms, and one of them avoids an ambiguity that the other doesn't, then pick the one that avoids the ambiguity.

If you have two synonyms, but the one that avoids ambiguity is inferior to the other one, then you need to weigh your options. How strongly do your developers rely on communication with the other team?

If their development rests on the communication quality (as was the case for my social security example), then you have a justifiable reason to pick the inferior option.

If, however, your developers don't need to communicate with the other team and can develop their tool just fine, then you pick the name that fits best (even if it is ambiguous to others).