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.

Comments

Popular posts from this blog

Managing Developers is HARD

I've been a software dev for a long time.  I've also been running my own software company for a few years now.  This is important information because of why I do these things.  I am a sofware developer because I love learning.  I slack off when doing a job that bores me, and software development always has something new to experience which keeps me excited and interested.  Why start a software company then?  That puts me in the role of manager rather than developer.  The truth is simple.  I've worked for a lot of companies, and I don't see any of them doing a great job of managing their software development.  That's not to say none of them have done a good job, but no one out there seems to be doing a great job.

How are they different?
A lot of companies get this part right.  Software developers are different from other employees.  The distinction is important in the same way it's important to acknowledge that an insurance agent is different from a construction…

When Is Software Done?

I have some very exciting news.  A piece of software I've been working on for over 2 years is released to the general public!  This is a little exciting if it were software I'd been working on for some big company.  It's very exciting because it's software I have been working on for my company.  That's right!  My company is ready to start selling software and start making money!

I'm not gonna use this blog post to talk about my company and what it does.  You can read about that in our press release.  Instead, I'm going to talk about the software industry and the concept of done.  Because, as with everything, it's more complicated than it seems.

Software is never really done
Actually that's a misnomer.  Software can really be done.  But done is sort of a quantum state--there and not there at the same time.  First and foremost, anyone can understand that software that works is complete.  If the software's purpose is to process a credit card, if th…

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 …