DaedTech

Stories about Software

By

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

By

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.

guy-digging-a-hole

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

By

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.)

edison

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.

GoofyOrgChart

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.

TriviaInterview

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.

[thrive_leads id=’7071′]

By

Rewrite or Refactor?

Editorial Note: I originally wrote this post for the NDepend blog.  You can find the original here, at their site.  While you’re there, take a look at some of the other posts and announcements.  

I’ve trod this path before in various incarnations, and I’ll do it again today.  After all, I can think of few topics in software development that draw as much debate as this one.  “We’ve got this app, and we want to know if we should refactor it or rewrite it.”

For what it’s worth, I answer this question for a living.  And I don’t mean that in the general sense that anyone in software must ponder the question.  I mean that CIOs, dev managers and boards of directors literally pay me to help them figure out whether to rewrite, retire, refactor, or rework an application.  I go in, gather evidence, mine the data and state my case about the recommended fate for the app.

ProjectManager

Because of this vocation and because of my writing, people often ask my opinion on this topic.  Today, I yet again answer such a question.  “How do I know when to rewrite an app instead of just refactoring it?”  I’ll answer.  Sort of.  But, before I do, let’s briefly revisit some of my past opinions.

Getting the Terminology Right

Right now, you’re envisioning a binary decision about the fate of an application.  It’s old, tired, clunky and perhaps embarrassing.  Should you scrap it, write it off, and start over?  Or, should you power through, molding it into something more clean, modern, and adaptable.  Fine.  But, let’s first consider that the latter option does not constitute a “refactoring.”

A while back, I wrote a post called “Refactoring is a Development Technique, Not a Project.”  You can read the argument in its entirety, but I’ll summarize briefly here.  To “refactor” code is to restructure it without altering external behavior.  For instance, to take a large method and extract some of its code into another method.  But when you use “refactor” as an alternative to “rewrite,” you mean something else.

Let’s say that you have some kind of creaky old Webforms application with giant hunks of gnarly code and logic binding the GUI right to the database.  Worse yet, you’ve taken a dependency on some defunct payment processing library that prevents you from updating beyond .NET 2.0.  When you look at this and say, “should I refactor or rewrite,” you’re not saying “should I move code around inside this application or rewrite it?”  Rather, you’re saying, “should I give this thing a face lift or rewrite it?”

So let’s chase some precision in terms here.  Refactoring happens on an ongoing and relatively minor basis.  If you undertake something that constitutes a project, you’re changing the software.  You’re altering the way it interacts with the database, swapping out a dependency, updating your code to a new version of the framework, etc.  So from here forward, let’s call that a reworking of the application.

Read More

By

The Journeyman Idealist: Architect of Programmer Paycuts

A couple of months ago, I mentioned that I’d be featuring more cross posts so that I could concentrate on my book.  I’ve lived up to that, mixing in the occasional answer to a reader question with posts I’ve written for other sites.  I haven’t queued up a good old fashioned rant in a while, but I think it might be time.

I want to start talking about topics from the book, and this particular topic, the “journeyman idealist” has relevance to a number of different, random conversations I’ve heard of late.  Don’t worry if you don’t know what “journeyman idealist” means — you shouldn’t because I made that up while writing my book.  And I’ll get to that and to our self-defeating pay tendencies a bit later.

Hourly Billing

Recently, I have consumed a great deal of content related to freelancing, consulting, and billing models.  This includes the following items, for those interested.

As I fall further into this rabbit hole, I become increasingly convinced that billing by the hour for knowledge work is a pile of fail.  Jonathan Stark of “Ditching Hourly” makes the case more eloquently in this episode, but I’ll offer a tl;dr.

Let’s say that a prospective client comes to you and says, “I want you to build me a website.”  Great!  Let’s do some business!

HighFive

Hourly Billing as a Zero Sum Game

At this point, you begin to think in terms of cost and how high you can go above it.  For the purpose of your business, this means “what is the minimum amount for which I will do this project?”  The client begins to think in terms of value and how far they can go below it.  For them, this means “what is the maximum amount I can pay and still profit?”  Perhaps you won’t build the site in question for less than $10,000 and the client needs the figure to be less than $100,000 for the venture to bring a profit.  Thus if you agree on a price between $10,000 and $100,000, you both benefit, though the amount of the benefit will slide one way or the other, depending on how close to each end point you settle.

If you were selling websites as commodities, you’d haggle, then settle on price, as with a used car.  But building custom websites by the hour differs substantially.  In that world, you strike a deal without agreeing to price.  You just both hope that when the dust settles, the price tag falls in the range of mutual profit, and no lawsuits commence.  But within that range, each party hopes for a different end of the spectrum.  And what’s more is that neither party knows the other’s figure.  You know only that you need more than $10K and client knows only that it needs less than $100K.

As the website provider, you want the project to take as long as possible.  It needs to go sailing past $10K, and hopefully as close to client’s upper bound as possible.  The less efficiently you work — the more hours it takes to build the site — the better your financial outlook.

Read More