At this very moment, I have a vocabulary about agreements and I’m sure you do too. As a team, our next goal is to know what words mean when we talk about them within the domain of agreements. It is also helpful for us to pick specific words for specific concepts.
To accomplish this, we will:
- Build a glossary
- Write some stories and scenarios
Build a Glossary
A glossary, unlike a dictionary, is just a list of words without definitions. I like starting with a glossary because it is simple exercise: pull out a blank piece of paper, find a white board, or open a empty text document; then write all the words that come to mind. Avoid delving into meanings and filtering words at this point.
…
Here’s my five-minute list of words: agree, agreement, contract, terms, conditions, proposal, propose, revise, revision, party, counter party, person, company, sign, signature, execute, executed, rescind, offer, notary, notarize, notarized, beneficiary, notify, notification, notified, dispute.
If you feel stuck, it’s fine to go find a primer or article on Wikipedia about contracts too. Here’s a list of terms there contract, agreement, promise, breach, remedy, damages, cancellation, formation, party, offer, offeror, offeree, promisor, promisee, acceptance, consideration, intent, mutual, bound, unilateral, bilateral, firm, expiration, lapse, agent, due diligence, clauses, exclusion, exemption, implied, express, severability, jurisdiction, liability, offer, proxy, quorum, repudiation, voids, warranties, indemnity, remedy, disclaimer, notice, quit, vendee, vendor.
Even though the lists together are quite lengthy, I’m confident that there are many other relevant missing terms. These fall into two general categories: terms we know but didn’t think about, and terms we we have never encountered in this domain. Our lists seem to have many similar terms. Some are interchangeable, some are generalizations of others.
When working as a team, you can create a glossary document by putting all of the unique terms into a single file. If you’re into bash scripting, you can use cat, tr, sort, and uniq to take all the words and create a unique, sorted list.
cat terms.txt \
| tr '[:upper:]' '[:lower:]' \
| tr ', ' '\n' \
| sort
| uniq > glossary.txt
Find the Essence
With our glossay in hand, let’s find four to seven verbs from our list that seem central to the idea of agreements. Picking verbs may seem arbitrary and subjective, but in my experience, the essence of any system is what happens. At this point, you can include synonyms, this should help avoid premature debate on the best verbs that describe the essence of what we will build.
- offer / propose
- consider
- accept / execute / sign / promise
- reject / refuse
- rescind / retract
- notify
- revise / modify
Did you notice that some words that weren’t in our original glossary snuck in here? No big deal, we’ll add them to the glossary. Realization is part of the creative process. Keep an open mind.
I see three other things worth mentioning: I didn’t write down very many verbs when building the glossary, almost every verb in the glossary has a corresponding noun, and the filtered list of verbs has some sort of order sequence.
At this point, I ask a two-sided-question: is there anything else we need to add? Is there anything we could take away? I’m on the fence about “notify” and would remove it if another term seems more central to our domain. I limit the number of words to seven slots for a reason: so that we have a shot at holding them in our short-term memory.
Write Some Stories
With these verbs we have what we need to write stories that ask and answer basic questions: who does this, when, and why? Our stories will use a structure, but will not specfiy how activities are performed. This helps us focus on substance over style.
Form #1: A Story
As a <who>
I can <do what?>
So that <why?> <why?> <why?>.
Form #2: A Scenario
Given <some precondition is true>
When <some activity or event happens>
Then <some outcome is true>.
I didn’t invent these two structures, but I like them a lot. As a maker I can use stories and scenarios to describe what needs to be built so that we know what to build, how to test it, and when we are done.
Now, let’s write some stories using our six word: offer, consider, accept, decline, rescind, and notify.
As a lender, I can offer terms and conditions to a borrow, so that they can consider them.
As a borrow, I can consider terms and conditions, so that I can accept, reject, or make a counter offer.
Oh look, nouns from our glossary! It’s very important for us to write before we edit, so we’re not going to refine these. Let’s crank our a few more.
As a borrower I can accept an offer so that the lender and I are obligated to fulfill our promises.
Given I have received an offer and it hasn’t expired when I sign it then I can no longer reject the offer.
As a borrower I can reject an offer so that the lender knows I am unwilling to accept the offer.
Given I have received an offer and it hasn’t expired when I reject it then I can no longer accept it.
As a lender, I can rescind an offer so that a borrower may no longer accept the terms and conditions.
Given I have sent an offer and the recipient hasn’t accepted it then I can rescind the offer.
Given I have sent an offer that expires in 1 week when 1 week passes then the offer is rescinded.
As I’m writing these last two stories and scenarios, I feel as if something is missing. It seems like there is something potentially problematic. Instead of getting caught up in additional research (or pointless editing) I’m going to move on and reflect on it later.
As a lender or borrower I can be notified when some activity occurs.
This seems pretty vague, so let’s use scenarios to elaborate a bit more.
Given a lender has offered me terms, when I’ve signed up for notifications, then I get an alert.
Take a close look at the scenario though. Does something seem off about it? Even though we should write first and edit second, it’s ok to make changes if you realize something is reversed. The point is to avoid getting stuck on a detail. Our cognitive capacity is limited, so we want to use 80% of it producing substance at this point.
Given I’ve asked for notifications, when a lender offers me terms, then I get an alert.
Given I’ve asked for notifications, when a borrower accepts or rejects my terms, then I get an alert.
Those scenarios are a bit better, but something seems a little strange about these too. Let’s move on though and continue writing some bonus stories. The original list of verbs is treated as a prompt, if other ideas some essential to the problem at hand, we should write them down too.
As a borrower I can prove a lender made me an offer.
As a lender I can prove a borrower signed or declined an offer.
We’ve done some hard thinking about the domain. We’ve written a glossary and some stories. If you have your own stories and scenarios, write them down!
Adjust Our Understanding
We have a better sense of the domain: what people do, when they do it, and why. There are some sticking points though.
Sticking Point #1: Rescinded / Retracted / Expired / Withdrawn Offers
I expect expiration of terms (or other forms of retracting an offer) to be a potential problem. Some nuance about what is allowed are well outside of my current understanding. It makes me wonder about times I’ve been offered a contract that hasn’t been signed by the other party: could they rescind the offer after I’ve accepted it? When can an offer be revised? What happens if the recipient of an offer suggests a revision? …I really need to research this before taking the next step.
Sticking Point #2: Naming
I didn’t whittle down terms to a a definite list to The Essential Seven Verbs of the domain. Why? Because we’re not there yet. Naming is a very hard problem and is something I want to tackle as part of our next step. It is important for me to show you my thought process.
Complexity
Building a glossary revealed complexity. Some words seem too specific, like lender and borrower. Some words words seem synonymous, like rescind and retract. Some words seem vague, like agreement. Some words words have contradictory meanings, like execute. These relationships and contradictions can make it very difficult to choose the best words to describe a domain. We could avoid this hard work by sticking with what we know, but bad names are like buying shoes that don’t fit: they work fine until you want to walk far or you want to run fast. Yes, they can be replaced, but that takes real time. Working together, consensus can be difficult to achieve. Take the time to reach it. Be collaborative.
In order to tackle the inherent complexities of language, we can write stories about what happens (the verbs). We increase our understanding of our vocabulary for a domain by adding context. Remember, the issue with unmitigated complexity is that it makes understanding a system hard. Stories help us describe the essence without having to reference an implementation.
I hope my approach shows you the benefit of starting with a glossary first and writing stories and scenarios second.
Next Steps
This was our goal:
Know what words mean when we talk about them within the domain of agreements
We made progress, but aren’t quite there yet. We’ll take another step by doing some research, writing and revising some more stories, and deciding on some names.
Left Field
Here are some anecdotes about agreements I’ve made in the past.
Good Story: Someone asked me for a personal loan of $2000. I found a promisory note template, read it to make sure I understood what it said, revised it to make sure it contained the parameters of the load, and printed two copies for each of us to review and sign. We each signed the agreement. I gave the borrower a check and I was eventually paid back.
Bad Story: I had a really nice guitar that I wasn’t playing very much. I knew a musician that could put it to use and offered to let him borrow it for free for an indefinite amount of time. He agreed to return my guitar whenever I asked him to give it back. I kept in touch with him every few months. At some point, he asked if he could buy it, but I said that I’d like it back in the future. About a year later, I asked the borrower to return my guitar. He stopped returning my calls and texts. It took months, but I finally got my guitar back. Fortunately it was a) my actual guitar and b) in good condition.
Ugly Store: I had a classic vehicle that wasn’t in working condition. When I had to move on rather short notice, a friend asked if he could purchase it for a fair price. I agreed. When he said that he didn’t have the money, he suggested I let him restore it and would split the cost of parts if and when I wanted the truck back. Being someone I trust, I signed the title over to him. When I got in touch with him a year or two later, he had sold the truck. He said he tried but couldn’t get in touch with me. It’s been a long time though, so it’s possible there was some detail about our agreement that I forgot.
I’m sure you have experiences of your own that help you understand the importance of agreements and what may happen without formality or intermittent communication.
My good, bad, and ugly stories aren’t really useful for designing a system. But they do provide us with something to consider when writing scenarios.