Skip to main content

Document it!

Anyone who's been in software development for any amount of time will know that a common issue in any team is a lack of documentation.  If you've been in the industry for more than a year, it starts to feel like "beating a dead horse" when talking about how we need more documentation.

You can try to appeal to people's emotions expressing frustration and a need for sympathy and empathy in the process, but that's just not how Software Developers work.  If you want to appeal to people like me, you need facts, and lots of them.

That's not enough though.  If you can convince your programmers to write the documentation, then you still have to convince management that it's worth the money.  The truth is, no one is on your side here.  What's worse, the guy who's touting documentation now, probably was against it last week.  It's a really hard sell.

This is my generous gift to you.  I'm going to give you the selling points that I've used right here.  I will note that these have worked for me in such a way that I am not losing my job while I spend the time writing documentation, but not necessarily on the level that the entire company is wildly encouraged to write documentation.  So it's only a start (I only started at this company a month ago), but I honestly couldn't give you the end-game solution unless I was in your shoes, so I'll get you started here, and you will have to be motivated to do the rest.  Fortunately, if you're reading this and haven't fallen asleep yet, you've got that motivation.

First, sell the developers

If the developers aren't on your side, then management doesn't matter.  Management doesn't code.  They barely know what the word code means.  If you want to get documentation in your company, your developers need to be on your side.  Ultimately, we make the decisions anyway (do I use a for loop or a foreach loop here?).  You're not going to get lazy developers to jump on the idea of writing documentation, but you can get even the laziest developer to tout how wonderful the documentation he uses is, so in order to sell the developers you need to write a bit of documentation to begin with.

It doesn't have to be much.  I spent about half a day yesterday talking with 10 different people trying to get the information I needed.  Once I had the info, I was able to document it in about 10 minutes.  So the half-day worth of research was a necessary part of my job, and the 10 minutes of documenting stuff was the work that I have to sell.  In terms of numbers, this bit of info is very nice for a developer.  But this isn't the cream of the crop.

It took me half a day to figure it all out because one of my team members had already gone through the process of figuring it out on his own and because one other team had actually written the API and was able to give some insight.  So the real numbers to compare are these, and this is the selling point.

It took one developer an entire week to figure out how to implement the API, which took another half-day for him to duplicate the work, which then took only ten minutes to document a list of instructions that takes 5 to 10 minutes to follow.  So now, all you have to tell them is that using your documentation to complete the same task saves them a week of work.  Once they use it and see how easy it is, they'll be jumping up and down about the value of documentation.  They may never write it themselves, but they'll always have your back when management asks that fatal question.

Then, sell management

Let's face it, Managers aren't that hard to sell on things.  If you put emotions in front of them, they'll laugh at you, but when you put money in place of those emotions, they get emotional.  Sticking with my API example from yesterday, I'll put money to the numbers.  We have 12 teams (I think).  Given that one team wrote the API and can likely implement it quickly, the documentation won't benefit them.  The second team, mine, who's already implemented it won't benefit from it either.  However, 10 other teams will.

An average developer in my area makes $80k per year which means $80k/52 = $1538.46 is what they get paid for 1 week of work (and if you include vacations that goes up, a lot).  So if we save each of those ten teams one week of work, we've saved the company approximately: $15,384.62.  Give those kinds of numbers to your managers and see if they think that 10 minutes was worth it.


Popular posts from this blog

Teams and Complexity

Let's pretend you're a car mechanic (I don't know, maybe you are).  But you don't work at some shop in town, you work at a bigtime auto-maker onsite at the factory.  You help build cars from scratch.  You work with a lot of other car mechanics, and various engineers of different levels.  If we were looking at the 1910s, you might be working for Henry Ford on one of the first ever assembly lines.  Either way, you have a specific part of the car you're responsible for.  Your skills probably extend beyond that, and you might work on a different part of the car each day as your manager moves you around to keep the factory efficient.

One of your coworkers, Bob, is a superb engineer.  He is very good at building cars, far better than you, and he does it faster than everyone else.  Your boss really likes him.  You often get stuck after him in the assembly line, so you know exactly what sorts of things he does.  He's not sloppy, but he likes to do things his way.  He w…

Managing Programmers

Working with other programmers is tricky.  That said, it's nothing compared to the job of managing programmers.  One of my favorite quotes about Perl is that (paraphrased) "a Perl developer is like a rockstar.  Now imaging having a bunch of rockstars in one room together and you will understand why you don't want an entire team of Perl developers."  It's not about Perl here though. What's important to understand is that any developer worth his salt is going to be like a rockstar.  And yes, there are a lot of professional developers out there who aren't worth their salt, but that's for another post another day.  Rockstar may not be the right term here, but think of it this way.  These guys are smart.  They may not be geniuses, but there's going to be things that they know that you don't and probably never will.

I've seen it more than once and it's not going to make some Product Managers happy, but I'm going to state a fact, an eleph…

How to identify a skilled programmer during an interview

How does one identify a skilled programmer?  No company that has interviewed me could tell the difference between myself and other programmers they'd interview.  The interview process is truly a game of luck in this industry--on both sides.  Both the programmer and the company are basing their actions entirely on luck.

Companies have come up with numerous methods to attempt to discern a good programmer from a bad one.  The best tricks they have include a series of math problems, algorithms, problem solving technique tests, and even obscure programming questions, some without definitive answers.  As an example: Is there an authoritative source of information on the core principles that define object oriented programming?  I've heard everywhere from 3 to 7.  In a field of research about a synthetic concept, an authoritative answer is almost impossible to obtain.

Programmers were then forced to study to the interview.  Careercup is one of my favorite sites for this.  This almost …