Fighting the good fight for software documentation

It must have happened 3 or 4 times this week.  Someone complained or threw a fit about having to create the tiniest scrap of software documentation.  Suck it up and write it down.  Quit whining and be an adult.  No likes writing documentation (just like no one really likes having to work) but IMO, documentation has to be done…

This latest incident came when a developer sent a link to a 70 slide power point presentation dissing the value of traditional UML diagrams.  Let’s just ignore the fact that the author probably could have fully UML’d his systems in the time it took to put together 70 slides and focus on the fact that this link was supposed to serve as justification for not doing something useful.  Like, “Look someone else on the internet agrees with me!  Now I don’t have to do it!!”  BFD.

I’m a fan of just enough documentation.  Just enough is the important part.  but around the office, I always get a dirty look when I say that we don’t do enough (ANY) Design Docs, Functional Specs, Use Case Documents, or Integration Guides.  Or I quickly get the default response “That’s not Agile” (I hate that phrase.  it’s such a cheap, cop-out, discussion-ender.  It’s similar to “I know you are but what am I”).

Now I know all the arguments against documentation but IMO they don’t come close to outweighing the benefits of decent, up to date documentation.  Take this as an example: any idiot can make an iPhone app because Apple has great iOS documentation.  Or a Facebook game because of Facebook’s documentation.  Amazon Cloud services, Google Maps, I could go on all day….  I just built a Sphero app because they gave me just enough documentation for each class & property & method.  It’s not like I can walk over to their office and ask them a question, I had to RTFM.

Furthermore I’d bet these companies don’t have teams of writers churning out word docs with every new release.  Their documentation is definitely automated somehow (javadoc is probably the most under utilized java developer tool in software development).

In summary: just enough, just in time and searchable documentation isn’t that hard to create.  But why does every developer throw a tizzy every time the word “documentation” comes up in conversation?  Suck it up already.  Or let me know how I can help because I want it so I could help produce it.  Sound fair?

Everything in this post is just my opinion and I do not consider myself an expert at any of this.  I don’t mean to offend anyone, I just needed a place to put the rant that was going on in my head.

I enjoy a nice "Under Maintenance" page

Sometimes it’s the little things that make a difference.  I was in the middle of adjusting my monthly budgets on my favorite financial management site,, when all of the sudden the site went into “maintenance mode”.  All the changes I made to my budgets were probably not saved and I have to go back and do it all again.  This would annoy most customers but for some reason (I’m attributing my lack of annoyance to the pretty maintenance page) I’m ok with it.

Since I work in software, I understand that peak hour maintenance modes are sometimes a necessary evil – although we do everything possible to avoid.  It’s refreshing when a company goes that tiny little bit further and pretties up their maintenance page.

I took a screen shot just because.


Make Me A Baseball Card is Live!

I’ve always been a coding tinker-er but most of my personal projects never really “went live”.  This year I made a new years resolution to design, develop and deploy an app all the way through.

I’m proud to announce that I flipped the switch and my first personal project went live last night!  You can check it out here:  There were lots of late nights and lots of coffee.  It was like having a 2nd part-time job.  Whew…

What is it? lets someone track their baseball stats and print out their very own baseball card.

When they click the Print Card link, we open a new window and they can print their card directly through the browser’s print functionality.  Here’s my printed card.

What’s next?

There are a TON of things I want to add.  Keep an eye on the facebook page for new features!


What Worked (surprisingly) Well – Sprint Tracker in Source Control 1

This past sprint retrospective the team proposed that we change up the way our scrum team reports on task progress.  The team proposed that we keep our Sprint Tracker excel document in source control.   Then prior to the daily standup meeting each team member would check out the document, update the time remaining on their tasks, and check it back in.

I am surprised at how well this worked!  I was expecting that nobody would participate or somebody would forget to checkin and then go on vacation or any number of possibilities.  But I’m proud to report our standups are more effective and efficient because we spend more time to discussing what was done, what to do and what things are standing in the way.

Let me try and explain in more detail. (more…)