Growing up, I watched a fair amount of sitcoms until I realized the basic plot device. Essentially, something happens where a character on the show makes a choice, is worried about the ramifications of that choice, and is then somehow deceptive. They keep having larger and larger miscommunications and problems as the show goes on, and more problems (and hence hilarity), ensue due to keeping the problems under wraps. Eventually the characters realize the mistake, and the show ends with everyone having learned a valuable lesson.

* Note: I am not affiliated with any of the sitcoms mentioned below, nor do they support me financially.

Full House

At some point, I got pissed because I just thought “Why doesn’t Stephanie just tell Danny Tanner that she wrecked the car instead of trying to hide it for like two more days? I’m pretty sure Danny’s going to flip out and kick Comet and ground you, but at least you get it out in the open. There’s definitely nothing to be gained from hiding it. Why would any rational person do this?”

Anyway, this process happens all the time on sitcoms. But the question that I thought of was: does it happen on software projects?

I suppose that part of this is a human tendency to attempt to delay pain whenever possible. You take a known undesirable and put it out into the future where it may or may not happen. Seems like a good thing, right? Maybe I can fix up the car with my piggy bank and Uncle Jessie’s spare tools, or maybe dad won’t notice the car being missing. Maybe I won’t be working on the project anymore. Maybe we can add a couple of people, that seemed to work for another project that was having similar problems. And maybe we can make it up. Maybe we can pull a few late nights or work some Saturdays to get this project back on track, or maybe we can just cut some corners here and there and fix them later when we have more time.

Unfortunately, by delaying communication, you lose a chance to align expectations early. There is a mental shift cost incurred when a stakeholder doesn’t quite know what is going on. The earlier that you can provide this information, the more time the person involved gets to stew on the information and try to come up with alternate satisfactory solutions or at least understand what is going on. In this sense, having transparency is key. No one likes to come to the end of a project that they thought was going well but see that things have gone amiss.

Unfortunately, in the real software world, hilarity rarely ensues from not communicating the true status of a project. More often money is lost and quality suffers due to a compressed schedule based on unrealistic expectations. People don’t get grounded, they get “let go”.

Home Improvement

Tim “The Toolman” Taylor always took a break around the twenty-minute mark of the show Home Improvement to talk to his neighbor Wilson across the fence about the problems he was facing during that episode. Tim would explain the situation, and Wilson would give him some sage advice that made a lot of sense to Tim. Tim would go back into the house armed with his somewhat rudimentary version of the wisdom that Wilson imparted, and things would get patched up.

It seems like Tim would have benefited from doing retrospectives before the twenty-minute mark (or, as sometimes happens in the software world, after the show, or maybe in the break room.) Maybe looking at the process and decisions made at five minute intervals throughout the episode would have helped to get at the root of the problem before it got worse. By the time that he got to the twenty minute mark, there was like one commercial break and five minutes of show left to resolve the underlying problems that were plaguing his family. They could have taken a kaizen approach to their family relations to lessen the chances that 2/3 of the way through the show the communication process was producing unsatisfactory results. I wonder how Tim’s experience with power tools and the search for ever more powerful tools mirrors some developers’ tendencies.

What this post hopefully stresses is communication of project status and expectations and evaluation of the development process. Do you have a sitcom example of your own?

Original article: Software as a Sitcom

I would go so far as to say that there should be open source technical writers. They look for interesting projects to write basic documentation for. While there are a smattering of tutorials for certain frameworks, they are not condensed, are not authoritative, and are often misleading because of changes to the framework or convoluted examples. When the core developers move at the speed of the forum or even IRC, it’s tough for a new person to have anywhere near that amount of knowledge. A centralized wiki with pertinent and up-to-date examples is quite useful.

If you are not yet a badass developer, this kind of project aids you in three ways. First, you gain experience looking at unfamiliar code bases and reasoning about them. This is especially helpful if you maintain code, and also assists you in writing more maintainable code. Second, you get some street cred for being closely involved with the developers on the project and working with them. You’re likely to learn something from the alpha geeks and advance your skills. Third, your writing skills improve, which helps you out in many areas over the long run.

In a nutshell, the kind of people who are building their own system or framework are generally not obsessed with documenting for average people. This could be due to time constraints or general personality traits. But the value that they create is wasted if people are not comfortable interacting with it.

Clojure

There is an interesting thread on the Clojure discussion group about making examples readable and general ways to help developers who are new to the language and want to code idiomatically. One post mentioned the Clojure page on concurrency. If you can read through the example code there and want to tackle concurrency (which is supposed to be a strength of Clojure), then I applaud you. This isn’t a knock against Clojure, it’s just so new that most everyone who’s interested has been playing around with it and trying to understand it better.

One of the most important points in the post is that to get a community rallied around a language or framework, it’s necessary to have good documentation so people aren’t put off by it. The Clojure folks are getting there, as there are a couple of wikis around that people dump stuff into.

qooxdoo

The qooxdoo framework illustrates one of my favorite examples of excellent open source documentation. When I first started looking at it, I was impressed by the amount of examples, pictures, screenshots that were included. The manual is rife with examples and code snippets.

They have a huge demo area that shows how simple effects can be created using at it. Looking at these demos, I started visualizing about how exciting it would be to work with this framework. As another great demo, it has an API documentation viewer, which itself is written with qooxdoo. It must have taken time to generate all of this…

Parting thoughts

On the other hand, one could argue that with a nascent open-source product, having too many people involved early is problematic for direction and quality density. Also, the people who create code which uses the product will constantly have to change their code because the underlying architecture or best practices change. It’s the bleeding part of the bleeding edge.

I’m not saying that I’m committing to doing any of this… Just thought that this was an interesting line of thinking.

Original article: Open Source Tech Writer