Archive for July, 2009

Emotions are important

Tuesday, July 14th, 2009

A friend of mine has a story that describes the clash between emotion-valuing and emotion-fearing conversation. While talking with a coworker about the Foobar module, he’d say, “I’m scared of what would happen if we put Barfoo data through it,” intending to start a discussion of the robustness of the code. Instead, the response would be, “Oh Paul, it’s okay. You don’t have to be scared. It’s okay.”

People, especially STEM-inclined people, often prize rationality over emotions[1]. Emotions are sticky and mushy and uncomfortable and hard to define. Numbers and facts are measurable and tidy[2]. I disagree; I think that both measurable information and fuzzy/gooshy information have value.

Metrics can be very helpful. How many units of work did we finish last release? How many bushels of corn were harvested from that field last year? How many milliliters of air can this person breathe out at once? Once you have a specific question, metrics and measurable information can help you answer it. Even if you don’t have a specific question, metrics can help compress specific data so you can see trends at a glance.

Emotions and fuzzy interpretations are also very helpful. I’m scared of what will happen to this code in a multi-threaded situation. I don’t feel secure about the performance of this system under load. This project is falling together perfectly. This patient looks woozy. Emotions are the high-level summations that your brain puts together from weeks or months of ill-defined input. They can’t be computed precisely, but as estimations, they’re very helpful.

This post was prompted by peripatetic axiom‘s Let’s talk about feelings post.

[1] The definition of “rational” is generally “agrees with whatever I’ve already decided is true”. This is a related, but separate, rant.

[2] I profoundly disagree with this too.

Cross-linked documentation

Thursday, July 2nd, 2009

I really appreciate cross-links in documentation. I think there’s value in both automatically-generated (e.g. Javadoc’s ability to mark up a function signature with links to all of the classes involved) and manually-generated (“If you want more information on how this interacts with threading, read The Foo System and Multithreading“) cross-links.

There’s one system of cross-linking that I’ve only seen on MSDN so far: links to other versions of the class or method being documented. Take this pedestrian method as an example. The default version of this page is for .NET 3.5, which is the current version, but a table on the right provides access for .NET 1.1 through .NET 4.0 as well as Silverlight. Version cross-links also make version information part of the ambient information of the universe, making it easier to find and correct false assumptions.

Many projects don’t need multiple versions of formal documentation active at once. For the ones that do, this is a killer feature.