Stories about Software


Automate Your Documentation

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

Few things, I’d say, strike boredom into the developer heart faster than the subject of documentation.  Does anyone out there really just love wrapping up development on a feature and then cranking out a Word document with a bunch of screen shots and step by step instructions.  Or, perhaps you fancy the excitement of pasting a legal header above a class you’ve just written, and then laboriously documenting all of methods, variables, and function parameters in the class?  If not that, how about the thrill of going back and updating comments that no longer make sense after the code has changed?

I suspect I don’t have a lot of takers at this point.

Documentation is boring, at least for the overwhelming majority of us.  After you’ve built a thing, you want to go build another thing — not rehash in laborious detail what you just did.  And yet, documentation is essential for communicating across time and teams to other people.  Your users will need documentation.  Future maintenance programmers need documentation.  Unless you’re going to be around in perpetuity to handle all that comes, you need to leave some sort of persistent knowledge transfer vehicle.

But that doesn’t mean it has to be tedious, repetitive, or boring.

Repetitive labor offers a certain counter-intuitive appeal, since it creates a “pain is gain” feeling of diligence and accomplishment when complete  But don’t be fooled.  People make many sloppy mistakes when doing repetitive tasks and drudgery is a terrible use of company money when you’re collecting a salary as a knowledge worker.  As people in the software industry, we earn a living automating grunt work out of existence, so let’s take a look at how we can help ourselves when it comes to documentation.

Read More


Collaborating with Outsiders to the Dev Team

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.

Developer news sites, blogs, books, and tutorials tend to speak at length about how developers should collaborate with one another to maximize team effectiveness. The subject of how developers should collaborate with people outside of their team often gets shorter shrift, however.

Personally, I find this to be a shame.  I think it tends to reinforce the stereotype that developers do a poor job of human interaction and need an organizational layer of people to translate between them and normal humans.  I would prefer to live in a world where people didn’t draw distinctions between “the developers” and “the business” because it was simply assumed that software development was part of the business.

For this reason, I’d like to offer some thoughts on how you, as a developer, can most effectively collaborate with non-developers — people outside of your team.  I will offer the caveat that some teams, particularly Scrum teams, are cross functional and thus include non-developers in the team itself.  I understand that, but for the purpose of speaking to the broadest audience, I will presuppose that your team is specialized in the sense that it is made up exclusively of software developers.  Besides, if your team does include other disciplines, it isn’t as if advice on how to collaborate with those folks magically becomes invalid.

Before getting into specifics, I want to mention two universal principles.  The first I will call out only briefly now and not again because it should be common sense and go without saying.  But, in case it doesn’t, treat these colleagues with courtesy and respect.  They are intelligent knowledge workers that simply have a different specialty than you do, and you ought to treat them as such.  If you can’t do it simply as part of being a decent human being, do it because acting like a primadonna is career limiting.  The second principle I’ll mention is that, because these collaborators are intelligent knowledge workers with a different specialty, you should endeavor to learn from them to improve your own work.

Read More


Top Heavy Department Growth

I’ve been somewhat remiss in answering reader questions lately.  Largely, I’ve lapsed because I’m choosing to focus on my upcoming book.  Nevertheless, I apologize for the lapse.  I do appreciate all the questions you folks send my way.  I’ll try to compensate today with this post about organizations engaging in top heavy department growth.

I’ll paraphrase this reader question because the specificity of the titles and information involved could make it sensitive if I didn’t take a couple of liberties.

I read your article about architect title over-specialization.  I’m a software developer with senior level experience.

Recently, my company has created “levels” above me.  I used to have only a dev manager above me.  But recently, the organization has brought in both new team leads under the dev manager and architects under a different manager.  Both take precedence over the existing developers.  These people now have authority to tell us what to do and they get to choose what they want to work on, leaving us with the leftovers.

I feel as if i’m being promoted down hill. Can you please advise?

How Companies Expand

If you’re up for it, I’ll offer a good bit of background reading to flesh out the terms.  If not, I’ll furnish minimal definitions here for reference.  A while back, I wrote a post describing the company hierarchy.  That post contains excerpts from my upcoming book, which you can pre-order and read on leanpub.

Here you have an apt illustration of the average company.  At the top, in executive roles, you have opportunistic individuals who define (and violate) the rules and culture of the company.  Then, in the middle, sit the idealists, who guzzle that same kool-aid and ask for more.  Finally, at the bottom toil the pragmatists, who roll their eyes at the company but put up with it for lack of better options.

Significantly, pyramids retain their stability by maintaining their shape.  Thus the most stabilizing growth pattern involves rewarding (over-promoting) loyal pragmatists, and hiring a bunch of grunts beneath them.  If you think of an existing pyramid that needs to get larger, you wouldn’t heap stuff on top.  Instead, you’d build from the bottom.  You’d pull some senior developers, make them architects or team leads to reward them hanging around, and hire a bunch of new grunts to report to them.

Read More


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


Using NDepend to Avoid Technical Debt

Editorial Note: I originally wrote this post for the NDepend blog.  You can check out the original here, at their site.

The term “technical debt” has become ubiquitous in the programming world.  In the most general sense, it reflects the idea that you’re doing something easy in the moment, but that you’re going to pay for, with interest, in the long run.  Conceived this way, to avoid technical debt would mean to avoid taking out these “time loans” in general.

There’s a subtle bit of friction, however, when using the (admittedly very helpful) concept of technical debt to communicate with business stakeholders.  For them, carrying debt is generally a standard operating procedure and often a tool, and it doesn’t have quite the same connotation.  When developers talk about incurring technical debt, it’s overwhelmingly in the context of “we’re doing something ugly and dirty to get this thing shipped, and man are we going to pay for it later.”  That’s a far cry from, “I’m going to finance a fleet of trucks so that we can expand our delivery operation regionally,” that an accountant or executive might understand.  Taking on technical debt is colloquially more akin to borrowing money from a guy that breaks thumbs.

The reason there’s this slight dissonance between the usages is that technical debt in codebases is a lot more likely to be incurred unwittingly (or improvidently).  The reason, in turn, for this could make up the subject of an entire post, but suffice it to say that the developers are often shielded from business decisions and consequences.  It is thus harder for them to be party to all factors of such a tradeoff — a role often played by people with titles like “business analyst” or “project manager.”

In light of this, let’s talk about avoiding the “we break thumbs” variety of tech debt, and how NDepend can help.  This sort of tech debt takes the form of “things you realize probably aren’t great, but you might not realize how long-term damaging they are.”

Read More