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