Stories about Software


How to Turn Requirements into User Stories

Editorial Note: I originally wrote this post for the SmartBear blog.  

Let me ask you something.  When you read the title of this post, did you envision it laying out some onerous process for converting gigantic Word documents full of requirements into “user stories” in JIRA?  If so, I’ll set your mind at ease right now.  It’s not that.

Indeed, I am not talking about the mechanics of taking the square peg of “traditional, waterfall-style requirements document” and jamming it into the round hole of some ALM suite’s agile workflow.  Instead, I’m talking about the more labor intensive practice of taking a document like that and using it to generate actual, agile-style user stories.  There is absolutely a difference, and not even a subtle one.  Putting, “ System shall cause cursor to blink twice after user types A key” into Jira and calling it a “user story” does not make it one.

Anatomy of a User Story

It bears asking, then, “since you say that’s not a user story, what is a user story?”  The most common way one sees it defined is via a mad lib.  “As a ______ I want to ________ so that _________.”  The definer then creates an example, such as, “As a personal banking customer, I want to know my account balance so that I don’t overdraft with my next withdrawal.”

To get a bit more philosophical, the user story has three components: persona, action, and value proposition.  The person is the “who” and it typically involves a description of a user or “actor” in the broader context of the system.  Some groups will actually define personas, give them names and characteristics, and then use the names, instead.  “Dave is a 35 year old stock broker with a checking and savings account, who…”  The user story is then, “As Dave, I want to know my account balance so that I don’t overdraft at my next withdrawal.”

The action is the way in which the user interacts with the system.  It is not framed in terms of minutiae and sequential, detailed actions.  Rather, it is framed in terms of goals that can be accomplished in a sitting.  There is a certain amount of art and subjectivity to what is an appropriate goal, but you’ll get the hang of it with practice.

And finally, there is the value proposition of the user story.  In my experience, this is the part that is both most frequently omitted and most important.  (It is also the part that is hardest to grok for people used to waterfall/contract-style requirements).  The value proposition explains why the person in question wants to do the thing in question.  And including it is particularly urgent for two reasons.

  1. If the value proposition is weak or nonexistent, you may deprioritize or eliminate this story altogether.
  2. If you hit a roadblock during a implementation of the action, you can immediately start thinking of other, more technically feasible ways to achieve the value proposition.

Read More


Resolutions Like You Mean It

Let me start this off on an improbable foot by saying I’m not huge on the concept of New Years resolutions, per se.  But I do value reflection and improvement.  And if just after the winter solstice seems like a good time for it, don’t let me stop you.

Finding Feedback

Last fall, I began participating in a mastermind group.  If you have a W2, your employer will typically offer you rather paternalistic guidance under the heading of career development.  I call it paternalistic, since it generally assumes that your goals include working for the company forever, and emulating the people that have worked there forever.  But, set that aside, and you can often extract a bit of value from it.  For instance, you’ll get someone’s take on how to secure a promotion or get assigned to a better project.

If you go the solo consultant or entrepreneur route, nothing like this really exists.  I don’t think someone has used the words “exceeds expectations” in front of me for about 5 years.  This I attribute to the fact that nobody uses those words outside of the corporate performance review.  And I haven’t had one of those in half a decade.

A mastermind group, more or less, fills that gap.  A few people get together at some interval (weekly, for instance), brainstorm, share ideas, hold one another accountable, and offer mutual advice.  Pound for pound, this offers much more individual value than the corporate perf review/boss one on one because it focuses entirely on my goals, not my goals in the context of being a perpetual good solider.

Measure It

At one of the mastermind group calls, we laid out goals for 2017.  Not having done this before, I lurked more than participated, to see what sorts of goals these meant.  The other participants laid out real plans, with real numbers, to do things like change revenue by X% or shave Y% of time off of some operational concern.

I came to the table with vague notions of, “I want to spend less time in cold places.”  Part of this results from my tendency to let lifestyle goals dictate work arrangements.  But part of this comes from sloppiness and the consultant’s peril of not taking one’s own advice.

Read More


What Technical Documents Should You Review?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look at the posts by some of the other authors.

If you’re anything like me in your programming proclivities, there’s a kind of singular impatience that leaps into your mind around the subject of documentation.  On the consuming side, whether it’s an API or a product, you have a tendency to think to yourself, “I don’t want to read about it, I just want to start hacking away at it.”  On the flip side, when it comes to producing documentation, that seems an onerous process; you’ve already finished the work, so why belabor the point?

Those are my natural impulses, but I do recognize the necessity for producing and consuming documentation surrounding the work that we do.  Over the years, I’ve developed strategies for making sure I get it done when it needs to be done.  For instance, even as someone who makes part of my living writing and teaching, I still segment my days for the sake of efficiency; I have writing days and I have programming days.

In order for this work not to get shortchanged in your group, it’s important to develop similar strategies or commitment devices.  The work needs to get done, and it needs to get done well, or else it won’t be useful.  And peer review is a vital part of that process.  After all, you create process around peer review for code — the developers’ strategy for sanity checks and spreading of knowledge.  Doesn’t it stand to reason that you should also do this with the documents that you create around this process?

Let’s take a look at some documentation that your group may be producing, and explore the idea of having peer review to go along with it.  We’ll look at an answer to the question, “what technical documents should you review?”

Read More


The Nature and Eventual End of the Journeyman Idealist

This is part 3 of the series about journeyman idealists.  You can read part 1 here, and part 2 here.

Hiring Ditch Diggers

We toil in an industry that loses sight of this basic problem, and no wonder.  In a simple scenario like that, we can reason about value.  But I’d like to employ an allegory to show how opaque that reasoning becomes at scale.  And in that opacity, the journeyman idealist reigns supreme.

Let’s say that I need to have a ditch dug in front of my house, and I have two competing laborers willing to do it.  The first one talks enthusiasticilly about soil aeration and the mineral properties of dirt in the area and whatnot.  He talks about the real craftsmanship that goes into ditch-digging and how people don’t realize that.  The other guy charges a few bucks less per hour, so I hire him.  How hard can it be?  And, besides, I can look out my window and see how it’s going.  If he fails and the ditch caves in or something, I can call the other guy that likes to ramble on about soil.


But now imagine that I can’t actually see any of the progress as it happens, and I will only know if it went well when one day, either sewage backs up into my toilets or not.  Wow, okay.  Same labor proposition, but with opaque progress and all-or-nothing results.  Earthworm Jim now sounds more appealing.  I have no idea how Jim’s knowledge translates into money or outcomes, but I take it on faith.

Journeyman Idealist Ditch Diggers

Now imagine that instead of my house, I run a massive construction company and I’m building several developments simultaneously.  Jim is my digging foreman, and I trust him to make sure we dig ditches.  Jim asks people lots of questions about topsoil acidity and demands they estimate how many aphids could fit onto a leaf.  All of that seems kind of stupid to me, but what do I know?  The ditches get dug, so it must be working.  And, besides, for some reason every ditch digger around seems to want to work here because we have “interesting soil” and Jim uses that outsize demand to tell them that aphid-know-nothings like them deserve to start at a lower pay grade.

I have hired, in Jim, a journeyman idealist.  And he hires in and indoctrinates more of the same.

Read More


Journeyman Idealists Inside of Companies

In the last post in this series, I introduced the concept of a journeyman idealist.  This post represents a simple continuation of that one — part 2 of a 3 part series.

Before I dive in, though, I’d like to remind everyone that Monday, the 12th, is the last day to enter the giveaway for free expert beginner swag.  Go here and fill out the rafflecopter form for a chance to win free stuff.

The Job Interview

When it comes to the role of the journeyman idealist, we can start with the interview.  Let me first say that I think job interviews are stupid.  Full stop.  I don’t mean that they need work — I mean that you should take that baby and throw it out with the bathwater.

I go into a lot more detail in my book than I will here, but the history of the job interview is basically, “an aging, grouchy Thomas Edison pulled a random management fad that would have rejected Albert Einstein out of thin air.”  That’s actually the entire history.  No one has meaningfully change it since it debuted, except that now it can be equally stupid over Skype or Webex as the original. in-person flavor.  (Seriously, research this — your jaw will drop.)


Imagine if I channeled Thomas Edison today (and were brilliant enough to have that kind of global influence).  I declared that, henceforth, all marriage should take place via speed dating.  Want to get married?  Show up, meet 20 or so different people for 5 minutes each, then marry one at the end of the night.  Everyone leaves married!

Now, further imagine that people just did this for the next 100 years, without really questioning the practice’s merits.  And then imagine yourself, 100 years from now, observing the world.  Books have been written about how to ask all of the best questions in speed dating and to give all of the best answers.  They have titles like, “How to Radically Alter Your Appearance for 4 Minutes” and “Acing the Marriage Carousel.”  Wouldn’t you ask, “this is insane — why do we do this?”  And wouldn’t you feel bemused at the answer, “well, sure, it’s not ideal, but what other option is there?  No, we just need to improve the lighting in the room and work on acoustics so it’s fairer.”

The Journeyman Idealist Job Interview

Job interviews are silly across the board.  But we, in the software development industry, take this to unparalleled heights of absurdity.  To illustrate my point, I did some quick research.  I searched glassdoor for “{Profession} interview questions” and calculated what percentage of results on the first page constituted trivial minutiae/extreme detail shop talk.

  • Lawyer: 0%
  • Dentist: 0%
  • Speech Pathologist: 0%
  • Lab Technician: 10% (generously — the 1 positive response was just asking if the person had experience in “pipetting”)
  • Accountant: 20%
  • Economist: 20%
  • Statistician: 30%
  • Electrical Engineer: 50%
  • Network Engineer: 70%
  • Mechanical Engineer: 80%
  • Programmer: 90%
  • Software Engineer: 100%

Notice anything?  Other professions, it seems, assess mutual fit through the process via common conversation.  We do it with a game of Jeopardy.  Journeyman idealists absolutely drive this dynamic.  To them the job interview’s primary purpose is not to bring on needed staff, but to set all right in the industry by stack ranking according to merit.  (Or, as Google introspectively points out, “to make the interviewer feel smart.”)  And you don’t accomplish that with fluff like “how would you help this company make money?”

Programmer Roles

If you’ve ever tried to sort out why some of us have the title, “programmer” while others have “software engineer” and still others “developer,” you’ve no doubt stumbled across things like this.  And that’s before we started calling ourselves things like, well, journeyman or craftsman.  I picked the linked explanation post at random — seems well written enough.  Every post I’ve found like this follows the same basic pattern.  “Let’s acknowledge that these titles are probably interchangeable… but I just can’t help myself and I want to categorize.”  And so, unlike, say lawyers or mechanical engineers, we call ourselves a bunch of different things right out of the gate.


And then we get to the vertical ranking.  Of course, you’ve got to have Software Engineer I through VII.  And then after that you graduate to senior, principal, and then fellow engineer.  Or, wait.  Maybe senior, principal and fellow are actually V, VI, and VII, respectively.  Or is that Rocky?  And what about tech lead, team lead, and architect?  And does all of that apply to developer and programmer or just to software engineer?

My gosh, when your head stops spinning, you’ll realize that “make sense of all permutations of programmer titles in O(n^2) time” would make the perfect technical interview question.

The Virus of Rank

Look at how our infatuation with the illusion of meritocracy pervades and defines our industry.  We concern ourselves with trivia during job interviews.  We invent six job titles per week to give ourselves and then set about arguing how they compare to one another.  And, perhaps most interestingly of all, we do this for free, and we offer up insane amounts of surplus value in the process.

Consider software developer lifeline stackoverflow.  I cannot even begin to describe how grateful I am for all of the answers it has furnished me over the years.  But what motor drives that world (and gives rise to “coder competitions” and the like)?  Our curious obsession with stack-ranking ourselves.  Stack overflow offers this in the most naked form imaginable.

We go on to the site and spend dozens or hundreds of hours offering free labor that goes for more than $100 per hour on the market.  But we don’t do it for the points, and we don’t do it for the badges.  We do it for the rank and for socially proving our position in this imagined meritocracy.

I know, I know.  Many professions now have stack exchanges.  But which ones occupy the top ranks of traffic?  You don’t even have to look, do you?

I know, I know.  The cred you build up there has real market value during interviews.  Do the math and see if that holds up.  At a paltry 5 hours per week building rep over the course of 4 years, your labor’s market value would have been $100,000.  I sure hope that better job you secured because of your rep pays you at least $200,000 per year.

The Mechanics and Soul of Journeyman Idealism

Software developers do an impressive amount of collaboration and offer impressive amounts of free help.  A genuine “rising tide lifts all boats” spirit seems to underscore much of our industry and drive us to help one another (even if badges and points do nudge us in that direction).  So why does a merit-sorting obsession lurk just beneath the surface?

I offer you a simple and admittedly depressing answer.  Simply put, we labor intensely under the false belief that programming skill strongly correlates with business value and should correlate strongly with pay.  Reality simply does not support this, but let me return to that shortly, after I describe how this creates the journeyman idealist layer that haggles over titles, chases points, and conducts interviews.


Axiomatically, in our world, programming skill has a clear, directly proportional labor to value, which, in turn, equals pay.  In the interests of the broader meritocracy and owing to our notion that we can somehow objectively rank programming skill, we gnash our teeth at the notion that some impostor might occupy the wrong position and rank.  (I’m guilty of it myself.)

Unchecked, this drives us to think of money and status as a zero sum game in our industry, which is ludicrous given that demand for our labor far outpaces supply.  And yet, we believe it anyway.  And that makes us set up wage depressing games and sniping all on our own, with little intervention from opportunists or traditional idealists.

Programming Skill Has Diminishing Marginal Returns

Selling out.  This is how we generally thinking of the transition into management.  Or, perhaps more benevolently, “taking your hands away from the keyboard.”  You cash in a larger payday but get away from doing what you love.

As programmers, we like to reassure ourselves that we could totally do this anytime we want, but that we choose not to.  We also then make fun of the incompetents in the layers of management above us, all the while harboring smoldering righteous indignation that they should command higher salaries.  We do all of the real work.

But if you want to get even more miffed, consider that people with roles like “project manager,” “Scrum master,” “management consultant,” “agile coach,” “trainer” and more also command comparable or higher bill rates. These days, I mostly avoid doing app dev for a wage or a bill rate because it tends to pigeon-hole people into low bill rate roles.

I’ll stop beating around the bush.  Programming has a definite wage cap, and organizations pay more for all sorts of “peripheral” roles.  This probably causes some cognitive dissonance for many reading, but there you have it — programmers command some of the least money in the programming industry.

And it’s because getting better at programming only creates commensurate value to a point.  If I need some REST endpoint written in C#, I’d rather have Jon Skeet, with his legendary knowledge of the language, do it.  But not so much so that I’d pay more than a few extra dollars per hour.

We fetishize programmer skill to an almost comical degree.  That’s fine, and even fun, in a hobby context, but self-destructive when wages are at stake.

Chasing Value and Money

I once worked with a man, whose identity I will obfuscate to protect the guilty.  He had an idea for a website that he eventually paid someone to execute.  The idea?  More or less plagiarize some kind of fad diet and then charge people a subscription fee to do it.  All he needed was studio time to record a bunch of videos and then a custom web app to create a paywall.

When the time comes to hire an app dev vendor, people like this guy contact 4 or 5 vendors and then pick the second least expensive one.  But let’s say that money was no object and time was of the essence, and he picked the most expensive (and thus, presumably, best) one.  He could have hired the most rock-starrin’, 10-X-n’, algorithm-interview-acin’ developer on Earth, and he would have had a terrible, lawsuit inviting product delivered faster and in more maintainable packaging.  The real 10x developer would have been the one that managed to talk him out of this hair-brained scheme.

And that’s a simple example.  That scenario illustrates, with the least moving parts, that you simply cannot correlate programming skill with furnished value.  That plagiarist could have hired a journeyman idealist consultant to conduct interviews on his behalf, forcing people to implement alpha-beta pruning on white boards, and not writing any code would still have won the day.

Until Next Time

Editorial Note: I started this as a single post, but it wound up being about 5000 words — more than 3 times the size of a normal post.  So, I’ve turned it into a series.  This is part 2, and I’ve added part 3 to my posting schedule over the next few weeks.  You can stay tuned for that when it comes out.  Or, you can have the whole thing now.  Sign up for my mailing list below, and I’ll send you the full post as a PDF.  If you’ve already signed up and want the PDF, just go ahead and subscribe again.  I’ve tested it — you won’t be registered twice.

Subscribe to the Mailing List...

...and receive the rest of this post now, instead of waiting a few weeks for it to come up in my post rotation. (If you've already subscribed, just submit again to receive the post, but don't worry -- you won't be registered twice. I've tested that with my own email addresses.)