The Power of Language

How Ubiquitous Language improved my project before it even began

Context

I am currently experimenting with some AWS services focused on Identity Management and Serverless. Since I learn better with a hands-on approach, I decided to build a small project to utilize these services.

The project will be a very simple Social Media Post Scheduler. As soon as I had the idea, I roughly jotted down the scope for an MVP (Minimum Viable Product) and an MLP (Minimum Loveable Product) with some out-of-scope improvements for the future.

First Draft

This is how it went:

### Product
A simple and intuitive social media post scheduler
#### MVP
- A user can
   - download/upload posts text file with plain text posts separated by " - -" (three hyphens)
   - select the time for a daily post (excluding weekends)
- The application will
   - post the top post in the document on the provided time
   - remove a successfully posted post from the document
   - won't post if the posts run out / empty document
#### MLP
- A simple UI to view, add and edit posts
- a history view of posts with timestamp
- customizable post frequency and time
#### Future
- a post appender API to simply add a post to the bottom of the post pool
- a post push API to simply add a post to the top of the post pool

Looks pretty good for a rough draft of a simple idea 💡
However, being a fan of Ubiquitous Language, I decided to invest a few minutes to identify and define some terms.
This simple exercise made me think about certain nuances of my idea in a way that I simply wouldn’t have done before starting to write the code.

Identifying and Defining Terms

I started out by defining a “post” and soon realized that in my mental model, both the ‘content’ and the ‘action of publishing the content’ were called “Post” 😅

As a result, my MVP had sentences like “post the top post in the document” or “won’t post if the posts run out”. That can be ambiguous. So I decided to refer to the content as “Post” and the action of posting as “Push”.

The 2nd thing I realized was that I didn’t have a term for the posts that were to be pushed. Instead, I sneaked in an implementation detail by calling it a “Document” because, in my mental model, I was planning to use plain text files stored in S3 for the MVP. However, in the future section, I was referring to this same document as the pool. It’s bizarre how the mind works when left unleashed 😅

Realizing this, I decided to officially call it a “Pool” and abstract all the implementation details (still keeping the implementation detail on a side note as it’s valuable information)

After a couple more terms I had the UL as shown below:

#### Ubiquitous Language
- Post
   - Social Media Post (text content)
- Pool
   - Pool of posts to be posted (a text file for MVP with posts separated by "---" triple hyphens)
- Next Post
   - Post at the top of the pool that'll be pushed next
- Last Post
   - Post at the end of the pool that'll be pushed last
- Push
   - Social Media Push (action of posting the content)

As I was altering the draft using these terms, I realized that I had thrown in a few more jargon that needed to be defined.
For example “select the time for a daily post “ or “customizable post frequency and time”

As I started defining time and frequency, I realized that I needed more terms to be able to explicitly state my mental model. I probably dove a bit too deep for this one but after spending around 10 minutes I made the below addition to my ubiquitous language:

- Period
  - Hourly, Daily (*default)*, Weekly
- Gap
   - none, even (*default*)
   - Gap between 2 posts 
   - none - All posts posted at the same time
   - even - all posts distributed evenly for a given period
- Frequency - Number of posts per period + *optional* GAP
- Start Time - Time of the day when the posts will start (*default* Immediate)
- Schedule - Frequency + *optional* Time
   - 1 post hourly
   - 1 post daily starting at 9 am
   - 2 posts weekly, starting at 12 pm

Definitely too detailed for an MVP or MLP, but I loved the way I could simply abstract away all the details behind just one term — “Schedule”

Revised Draft

Finally, I was ready to alter the draft using my Ubiquitous Language
Here’s the final version:

### Product
A simple and intuitive social media post scheduler

#### MVP
- A user can
 - alter an entire pool 
 - select the Start Time (Frequency is 1post per day)
- The application will
 - push the next post at the given Schedule
 - remove a successfully pushed post from the pool
 - don't push if the pool/post is empty
#### MLP
- a simple UI to view and alter the pool
- a history view of pushed posts with timestamp
- customizable schedule
#### Future
- an api to add Last Post
- an api to add Next Post 

As you can see, the resulting draft is a lot more concise and clear. (scroll up for a comparison)
Ambiguities and vague descriptions were replaced with precise terms. This clarity made every aspect of the project more understandable and less prone to misinterpretation.

Impact on Design and Implementation

The influence of UL extends beyond mere semantics; it has a significant impact on the project’s design and future implementation.

Design

With UL in place, the design process becomes more straightforward. Clear terminology aids in structuring the application’s components. For instance, the definition of a “Schedule” helped model a “Schedule” component that will abstract all the nuances of start time and frequency.

Implementation

As we move forward with implementation, UL will be reflected in the code and the terms will become classes and attributes. Having a shared vocabulary that is reflected in the code will enhance collaboration and reduce the chances of misunderstandings.

Conclusion

The journey from the “before” to the “after” version of my project was a testament to the power of Ubiquitous Language. It brought clarity, conciseness, and a positive impact on the project’s design and future implementation.

Was it perfect by the end? Likely not. But it isn’t supposed to be. UL evolves and so does the model. But taking a few minutes to think about the language and the terms probably saved me hours of confusion and refactoring at a later stage.
So, the next time you embark on a project, consider the magic of language. A shared and well-defined vocabulary can transform your ideas into a finely-tuned masterpiece. Even at a very early stage. Give it a try, and you’ll experience the transformation firsthand.

If you found this post insightful and want to stay updated with more tips and experiences, I invite you to follow me on Medium and LinkedIn for future content.