Tech

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.