Better Code without Code: Framework for Understanding What You Really Need to Code

This is a rough transcript from my presentation at Women Who Code May 2, 2019. http://meetu.ps/e/GGnlp/jrx00/f
Update: Whoops corrected a ton of typos and missed last slide which talks about where the framework comes from.

Hi everyone! Thanks for joining us here today at Ada. My name is Kris. I’d like to introduce you to someone today.

Meet Meowtefina. She’s a modern day wizard. She can turn words like MVP, Blockchain, Omnichannel and Social into magnificent feats of software engineering that we call "Apps" (does air quotes).

Meowtefina works at Catmart.com, as we all know, is the largest online food store in Catnada. Not to be confused with Canada.

There was danger at the company. Cartmart.com needed to expand fast. The CEO of Catmart.com saw an opportunity to target unhealthy millennials. Millennials are choosing to eat healthier. We must have healthier food options on our store.

So the product owners at Catmart.com researched all the ways they could have healthy options. They said we must partner with Kaleforce.com, the leading supplier of kale. Let’s show Kaleforce.com’s products into our product page. We’ll be rich. They said.

Meowtefina’s never integrated with Kaleforce.com before. So she looked at their website. They seem to have an API and some documentation. Should be a piece of cake. Famous last words for any developer.

Meowtefina being the modern day wizard, was able to show the products on the site. She was able to merge the results from Kaleforce.com then display it on their list of products. She was able to ship exactly what the Product Owners said. Amazing.

It would be great if I told you it went happily ever after but that never happens in software, right? Shipping is not the end of our story. It’s the start. The likelihood of shipping perfectly is usually very low.

And so it happened. The released it to beta. Moments later, beta users were starting to find bugs EVERYWHERE! There were 3 main issues that came out.

1. Users were reporting inconsistency: Sometimes Kaleforce.com products showed up sometimes nothing.

So Meowtefina took a look. She found out that if Kaleforce.com had no more available products, their service threw an error. She never expected this.

2. French users were reporting that they could never find Kaleforce.com products.

So Meowtefina took a look. French users were typing lekale (or what we know is the French word for kale). She found out that Kaleforce.com only accepted english characters. It won’t show results for lekale but only for the english word kale.

3. Worst issue of all, the app was crashing. She found out that Kaleforce.com could not handle a measly 5m requests per second.

Meowtefina fixed bug after bug after bug until she couldn’t take it anymore. Like her app, she crashed. Literally. It was tough. Like us, she felt powerless and defeated. She wanted to do better and be better so meowtefina did what any of us would do in that situation. She asked a friend for advice.

She meet her friend Catrina. She’s a psychic, senior software developer and influencer on Insta. Meowtefina asked for some advice. How could she deal with all of this? How does Catrina do it? Catrina told her that she had to be Psychic and foresee the future.

How could she be do that? Catrina look at our crystal ball.

It was showing these letters... P. E. A. G. S. It must be an acronym! Catrina's powers can only unlock one word at a time. Meowtefina would have to pay 50$ a month for the next 5 months to find out all the letters but the first month is free.

Sounds like a deal so Meowtefina went ahead and got it. Katrina said that she must use it in her problems and it will reveal itself to be useful.

She had to remember what was the original request. She had to "Show Kaleforce.com's products on our site".

She went to Catrina again to see P.E.A.G.S.. The first letter was P. It revealed itself as Pre-condition. Before starting to take on task, she should understand what must be true.

If she stated that before I take on this task, we assure ourselves that (1) Valid API Key (2) Enough API calls (3) their API is up. That's 3 or more bugs right there.

That itself reduces the potential bugs and limits the scope. It can help her focus on a singular task which is showing kaleforce’s products. Meowtefina can work with the other developers so they are the ones that can make sure these three things are always true. Those developers can have focus as well because they limit what everyone has to worry about.

The second month, Meowtefina came in and Catrina showed her the next letter. E. It was Exception Paths.

What is that? It was about understanding all the way this situation could fail. What are the things that would prevent us from showing Kaleforce.com's products into our site?

We could think about 2 situations already. First, the products were sold out and second, the API is too slow. With those in mind, we can think of some high level solutions on how to handle this situation. Maybe we can cache the product and mark it as sold out? Maybe we can show a loading bar? We can think of ways of how to create a better user experience when these things happen.

One thing to note is that, we actually don't need to solve them right away. We want to be aware and have an idea. What's equally important is to figure out how likely these situations will happen then tackle them at the right time and order.

The third month came along and Meowtefina already spent $100 dollars. It better be good. The next letter to shown was A for Alternative Paths.

Alternative paths are all the different cases we need to consider. Some are common cases while other are edge cases. Similar to Exception Paths You don’t have to handle everything. Tackle the highest probability ones first. You also don’t have to handle this all in one ticket.

In Meowtefina's case, we saw some different use cases and new ones like (1) Users type the non-english word for kale and (2) some users were allergic to kale. We can think of high level solutions here too. Maybe if the user really wants kale, they are willing to wait a second or two?

What's important is that we are building our knowledge about what can likely happen so that we can build the right solution at the right time.

We’re almost there! We’re at G now. G is not Gangster but Goals. The first thing you should build is not code but empathy towards the user. Put yourselves in their shoes. What’s important to them? How can we solve their problems? Maybe this gives you more ideas on how to solve their problems.

Who? How many? How often? When? On what device?
Answering these questions help us design our code better.

You eliminate a lot of work or potential bugs by building empathy towards your user. For example, maybe 98% of millenials shop on their iPhones. Maybe you just need to support Safari and that’s enough.

How many and how often? If you know beforehand the number of users you’ll have for this feature and what times they are active, you are eliminating a lot of work. You can choose to scale at certain points of the day to handle it.

By understanding the user, you can limit what you need to do. You can make your architecture and code more pragmatic.

We’ve made it to the last letter! $200 dollars later, we’ve unlocked the last letter which is S, Simplest Path.

What does that mean?

We should build the simplest thing we can first. That means we find the easiest code path. The least exceptions and alternative paths. Let's build the simplest and start there.

For Meowtefina, it might be this.

1. User typed Kale in searchbar
2. Kale API gives us results that can be ordered
3. User views product info
4. User orders Kale

Let's limit what we need to build and ship it. After that, build on top of that with the knowledge we have in the previous letters.

Whew! That was a lot of stuff. Let’s review. Can you say it with me?

P: Precondition: What must be true before we take this on?

Chanting ensues

E: Exception Paths: What are the ways it could fail
A: Alternative Paths: What are the other ways the could achieve it
G: Goals: What does the user really want
S: Success: What’s the happy path

Now, at this point maybe you already have some violent reactions. Just like with anything, there ares pros and cons to using P.E.A.G.S. Just like with other frameworks, it's best at certain scenarios.

most of the slide is self-explanatory except the one below
For product-market-fit, when you're still trying to figure out what is your product and who is your user. It's hard to have all the answers to P.E.A.G.S. at that point. You may want to hack and iterate fast and PEAGS is a lot more difficult.

Fancy diagram to look super legit

Let us take a step back and join Meowtefina. She was asking How does it work in practice? What’s the workflow like?

Catrina the psychic told her. Start with the goal and understand our users. You can ask your product owners help here. Then feed that information into the the P.E.A. with whatever system you need to depend on. Maybe it’s an API or legacy application structure. What do you not need to worry about? What are all the different cases you need to handle?

Once you have a grasp on that, slowly build on it. Build the simplest case. Then add the highest likely scenarios. What’s the most likely error? What are the highest probability alternative paths?

Why don't we try it?

Asking the audience to help Meowtefina with the next requirement. Some samples answers shown below and in slide

P: Precondition: What must be true before we take this on? API is Up
E: Exception Paths: What are the ways it could fail? Kaleforce can't ship to Ottawa.
A: Alternative Paths: What if I want to send my friend kale so they can also live their best life?
G: Goals: Who? Millenials with iPhones who order kale at night after work.
S: Success: What’s the happy path? Start with iPhone support at low peak, in the morning, with a supported city like Toronto.

With that, Meowtefina leveled up and became a superhero.

Source:
If you'd like more information about this, check out the book Writing Effective Use Cases: Alistair Cockburn. All of the ideas and concepts (except cats) are from that book.

Thanks to Women Who Code for letting me share this presentation! Join them at https://www.womenwhocode.com/

Some photos at the event.