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

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 …

Dependency Injection - You're doing it wrong!

So I have worked at a lot of places and seen a lot of different styles of programming.  Early on in my career, I became acquainted with the concept of dependency injection.  It was a hard topic to grasp, but I have learned understand it deeply.  Now, when I step into a new application that uses it, I can very quickly see the flaws in the implementation, and there's a common one I want to talk about today: global singletons.  But we'll get to that in a minute.

What is Dependency Injection?
Dependency Injection is exactly what it sounds like.  You use it to inject your dependencies. The unique part about Dependency Injection though, is that you can do this at runtime.  Now this sounds fancier than it is.  By inject we don't mean they're downloaded for you.  You still have to have all of the parts installed where you want to run your app.

Dependency Injection is somewhat of a complicated topic to a newbie.  Let's start with defining the word dependency here.  Specific…

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…