cocktailcoding-blog

[cocktailcoding-blog]

Story Mapping: An Appetizer

Welcome back! Last time I introduced who and what Cocktail Coding is, as well as project conception. In this post I will go over a concept calling ‘Story Mapping’ that I recently became aware of and we have found to be extremely useful in driving out a more concrete definition of what a software system is in a very organic yet comprehensive manner. As we are by no means experts of this technique I will use more of an example-based rather than theoretical explanation.

Once our design document had defined our primary vision and set a rough scope, we moved to a fairly modern approach called story mapping. Story mapping is a process for driving out detailed yet non-technical requirements by enumerating the steps a user will take when going through their tasks. In order to figure out these tasks, you must first identify the users of the system. This is done by identifying Personas, which are stereotypes of your common user. The academic example would be a point of sale system. It is a common technique to name them with a mnemonic such as ‘Courtney the Cashier’. This makes it very easy during design and development to argue for or against a particular design/implementation referring specifically to the user(s) it will affect (“Courtney doesn’t want to implement her password for every transaction”). You will flesh this persona out with their drives, desires, and experience as well as any other relevant information in terms of how and why they use the software system.

From here you identify the tasks Courtney would take throughout her day. Simple things such as log in/out and lock/unlock the cash register and check out a customer. Marty the Manager might have tasks such as manager override, audit register, and add/remove cashier (though this might be more of a task for Ivan the IT Guy). Some tasks will be shared (such as log in/out) so we will indicate this rather than duplicating them. 

The next step is to break down these tasks into the logical steps a user would take. For login a user would enter their username/password, they might specify how long they want to stay logged in, and they will eventually logout. For each step, you enumerate all the alternative paths they may take, for example login might be with a password, or in a high-rent store it might involve biometrics. Logging out could be an explicit action, or perhaps there is a proximity sensor that locks the register when the user walks away. 

This step is where we really started to see future possibilities for enhancement as well as obvious but easy to forget features pop up. Below I have attached a picture from our actual storyboard for logging in and out for the webapp we are creating. The idea of facebook/gmail logging in and out was generated due to this process, as well as password recovery and mechanisms to implement it. This would be a good time for me to note that putting something on your story map is not committing to it now or in the future. This falls in the category of brainstorming where anything goes and nothing should be cut. 

I shouldn’t go further without mentioning the tool we used for this is Trello.com. While it is not perfect for this purpose as stories with a lot of columns get a little wonky and deleting/hiding columns is kind of weird, for a team collaborating remotely it worked quite well. One possible tool more oriented towards this that is still under development is cardboardit by DevJam, an Agile consulting company. 

Something else you may notice in this diagram are steps marked with a red bar. These form what may be called a ‘walking skeleton’, ie the most barebones possible path through a system that would accomplish beginning to end functionality to provide at least a bare minimum set of functionality. Identifying all the possible steps, and then the most core indispensable ones means once you implement this walking skeleton, you would be ready for an alpha test, if not beta depending on the goal of your system. Having this accelerated testing cycle will help shorten feedback cycles which has a tendency to create better software as developers have more time and more iterations in which to bring software up to a state to fulfill the needs and desires of the users. 

For people interested in the more of the mechanics, while there is a general flow from left to right, it is not a strict requirement that every column be executed to complete a task. This example is a little unusual as it is really three tasks (login, logout, and lost password retrieval) baked into one for practicality reasons. But for example here you see that I have no step in ‘specify session duration’ we can implement a working version of the app without an explicit specification of how long the user wants to stay logged in. The following two pictures depict an example of a full transaction for our PoS example. In this example, applying a loyalty/reward card is not a necessary step as the customer may not even have one.

In these diagrams you have probably noticed the orange bars on certain tasks. It is typical to denote the difference between steps that are directly correlated to user actions (e.g. scan item) and things that are done by the system as part of the process but not directly connected to a user action (e.g. apply digital coupons). In the classical post-it note form, one approach is to rotate these steps 45°. Regardless of the mechanic used, this distinction helps to keep the story map clear and readable.

I hope this has provided some insight into the technique and if you’ve never encountered story mapping before I would encourage you to seek out more materials, I’ve included some good starts at the bottom of this post. Next time I will get into how you move from these non-technical steps into vertical slices you can implement and have app features up and running almost scary-fast. Until then, give those code cocktails a stir!

More info on Story Mapping:

The original proposal by Jeff Patton, regarded as one of the originators of Story Mapping

Cardboardit, the app I alluded to earlier for story mapping digitally (David Hussman, who is also attributed as an originator and evangelist for story maps, is associated with DevJam)

A fairly good simple and clear analysis of story mapping in post-its

[cocktailcoding-blog]

...and it begins

Hello and welcome! What is cocktail coding, and who are we, you may wonder? We've been mixing a metaphorical coding cocktail for the last two months or so. To develop our yet-to-be-announced recipe site, we decided we wanted to follow some of the latest software development practices, utilize effective tools, and leverage good coding frameworks and libraries. I'll try to avoid making these posts look like a buzzword smorgasbord, however every technology/technique I mention will be something we've spent hours learning, setting up, cursing at, and eventually getting to work for us (or abandoning and the reasons). These first few posts will describe what we've gone through thus far until we catch up to our current status.

As far as who we are, I am one of two professional software engineers taking on this project in my spare time. My professional expertise lies primarily in c# and the .net stack, while my knowledge reaches from assembly to c++ to scheme. I have worked at a 'lean' software company before so have some modern process exposure. My co-conspirator primarily works with python as well as web (html/js/css), and pretty much just has 'traditional' process experience. Our project was born out of a desire to experiment with modern processes as well as technologies and techniques. The recipe aspect comes from a shared interest in cooking and perceived lack in existing sites that I won't get into at this time. We live in different states and thus all of our problems have to be solved with remote-enabled technologies.

Now that I've set the stage, let's get into it. Idea inception occurred in IRC. At this point I don't remember who had the original idea, and I'm not sure it matters. IRC is a great low level technology to facilitate ad-hoc discussions among people not in the same location. Even within a physical office building IRC has a reduced overhead vs calling people into an office or meeting room. Unlike IM, IRC (or chatrooms) don't demand attention with flashing icons or pop-ups (unless so configured) and can naturally support 2+ users. The idea quickly grew, with both of us bouncing ideas of what we would want in such a site.

As the idea expanded we moved to google docs, which allows collaborative editing and more structured activity, producing a rough design document rather than just the stream of conversation that is an IRC log. We captured our goals and vision, defined our userbase, identified challenges and competitors, determined stakeholders, and started defining scope. One aspect of modern documentation is to strive to be minimal yet effective. In this vein we avoided strict low-level requirements and instead tried to capture the fundementals of what we wanted to achieve. With our site focusing on cooks and recipes, we defined several types of cooks and people interested in recipes we are targeting. We also defined several key recipes that best represented the type of activity and content we hope to support. We then refactored those recipes into archetypes that we can use more generally as a loose type of acceptance test. We did capture a few features that we had come up with in our IRC discussion that we thought helped to further nail down our goal.

Once we had idea of the scope, we brainstormed and came up with an initial technology list with the technologies we thought might best help us realize our vision (at the bottom of the post for those interested*). With an idea of how much functionality we wanted to implement and accounting for the time it would take to learn the technologies listed, we come up with a very rough release schedule. Between not having an in-depth design (that'll be the next blog about story mapping), the unknowns associated with learning new technologies, and the fact we'd be tackling this project in our free time the dates we put down were very loose (and in fact have changed several times). That being said, putting down goals has already helped in keeping us on track and giving us visibility into the reality of development vs gut feeling.

I could easily keep going but I think I’ve already covered a lot and don’t want to ramble. Next time I’ll talk about story mapping and how it has not only helped us construct a comprehensive idea of our product but driven and shaped our entire development experience. Until then, keep on mixing!

*Initial technology list:

db: couchdb (since decided against), postgres

server: python, django, django rest framework

webapp: html, javascript, jquery, bootstrap, knockoutJS, requireJS