Call it what you will; a personal philosophy, a theory, idiotic, but I have long held the belief that every personality trait is a double-edged sword. Patience is a wonderful attribute but, taken too far, can turn to apathy. Dedication to an ideal or a goal is very admirable, but not when it is to the exclusion of all else. Finding balance in life is one of the most difficult and impactful things we can do.
For me, I struggle to find the line between finding the best way to accomplish a given task and actually getting the damn thing done. It’s easy to spend so much time improving a process or an approach that, when it comes to actually putting it into action, you have to rush it and disregard half your work to make a deadline. That’s why, as often as I can, I try to remove the necessity to rethink things on a continual basis. That doesn’t mean continuous improvement isn’t still a goal, just that I’m going to check-in and improve on things every so often rather than changing things in the middle of a task. This provides consistency and a big benefit to efficiency because now we can template and automate things since they aren’t changing every single time we use them.
Having a template for each card/ticket we create accomplishes a couple of things. First, it ensures that I don’t forget to include something I need to. Second, it is one less thought process I have to put energy into when dealing with already-complex issues.
The late Steve Jobs famously wore the same outfit every day. Many other notable figures such as Mark Zuckerberg, Albert Einstein, and President Obama did something similar. The reason? Decision fatigue. The idea is that your brain really only has the capacity to make so many decisions in a day. The more menial the decision, the less of that budget it uses up, but it still uses some of it. By eliminating a decision, we give ourselves a little back in terms of brain budget for the day. That’s the goal here.
So without further ado, here is my mildly-interesting-but-hopefully-useful template for capturing user stories, acceptance criteria, and all the other information needed for a feature.
I like Atlassian’s definition of what a user story is. “A user story is an informal, general explanation of a software feature written from the perspective of the end user. Its purpose is to articulate how a software feature will provide value to the customer.”
User stories are meant to answer the question “what’s the point?”. It’s the lens through which all the other information should be viewed.
We used to have designs documented in a single spot and just put something like “See article detail design” on a card. We’ve found it’s much more helpful to link to a specific design or a specific part of a design wherever possible. Especially as front-end frameworks and new ways of thinking about content management drive us to be ever more modular and component/widget-based. I also find it very helpful to include a quick screenshot of the feature since, often, designs do not break things down component by component but have them in context.
Rarely does anything ever get finalized in a single sitting. Usually, there are initial requirements, design reviews, questions/clarifications from the design review, re-evaluation of requirements, technical considerations, and so on and so forth that all need to get hammered out before we’re ready to put a feature into a sprint. This section helps me keep track of where we’re at with a given feature, so I don’t have to remember what we still need to figure out.
Assumptions are a common thing in agile development. Here we’re listing things like
Anything that we’re basing our acceptance criteria off of that would otherwise affect the content entry or user experience of a feature is listed here.
This is one of the most important sections. Acceptance criteria are the details that provide a checklist for developers and QA alike. That doesn’t necessarily mean this needs to be loaded with complexity. Sometimes it’s as simple as listing the parts of the feature that are editable by the editor and which are static. Often we will list things here that are not obvious when looking at the designs, such as what API the data is coming from or what happens when I click that button over there.
Automated UI testing is becoming more and more integrated into everything we build. If you’ve ever run into a situation where you get a customer complaint that a form isn’t working and, after investigating, you discover it was a regression problem that only appeared on production from a deployment you did a week ago, you’ll understand why. Websites are large and complicated. It’s impractical to expect humans to check every single page, section, feature, etc., every time a change is made. Automated testing allows us to let the system do the work for us on the most important sections of the site to make sure those forms still work and that the 3rd party API we’re using to bring in job results didn’t change without warning and break things.
The reality is that there can often be months between first writing all the details for a feature and actually implementing it. I can barely remember what I was working on two hours ago let alone how we decided we were going to build a feature on one of our five projects six months ago. This is the spot where we list notes to ourselves about how we planned to solve a particular problem or what architecture we’re going for so that future-us doesn’t have to swear more than necessary.
Okay, so this is not going to be an in-depth dive into automation. Instead, I just want to share with you what I use. Rather than have to use any brainpower to remember where I’ve written my template so I can copy and paste it into the card/ticket I’m writing, I just wrote an AutoHotkey script to do it for me. If you’re not familiar with AutoHotkey, it is a scripting language that can do pretty much anything you can do on your computer. Open programs, automatically copy text from anywhere and search Google for it, etc. For a complete guide on how to get started with AutoHotkey you can check out their docs here.
In this case we’re really just using it for a text macro with some added flair. You’ll notice a bunch of “extra” characters in the below script. We use Jira as our project management software so I’ve put Jira-flavored Markdown into it to pre-format a bunch of stuff. The Markdown Jira uses is relatively standard but, depending on the system you use, YMMV (your mileage may vary for the non-l33t 5p34k125).
::]us:: ; INPUT USER STORY TEMPLATE
Story =
(
**User Story:**
- As a __
I want to __
So that __.
**Design Links:**
- Link{Enter}
**Outstanding Questions:**
- {Space}{Enter}
**Assumptions:**
- {Space}{Enter}
**Acceptance Criteria:**
- {Space}{Enter}
**UI Testing Needs:**
- {Space}{Enter}
**Technical Notes:**
- {Space}{Enter}
{Up 18}{End}
)
send %Story%
return
Basically, all you have to do is type “]us” and hit “space” or “enter” and you’ll wind up with exactly what you saw in the template above. Hopefully, some of you find this useful and take it and make it your own. Set your own shortcut and update it to reflect your system and needs.
We love to make cool things with cool people. Have a project you’d like to collaborate on? Let’s chat!
Stay up to date on what BizStream is doing and keep in the loop on the latest in marketing & technology.
