At work, I've been pushing for a Javadoc-like tool for the code my division maintains. However, it's been difficult to explain the ...

Wait, I'm sorry, you wanted to talk about silverware? Don't worry; I'll talk about silverware, and sorting it, in a bit. But I'll be straight with you: this article is actually about the importance of partitioning tasks so as to bring your full attention to bear on each part. Or rather, it documents my little struggle to articulate this idea in a business context.

I apologize if I mislead any silverware-sorters.

Document, Document, Document

The code I work on undergoes heavy maintenance: in addition to a continual sequence of small fixes, we refer to the code constantly to understand its behavior in detail. Despite this, the code is not easy to navigate: about half of it is stored in a database and there's no integration between the database and the IDE, so we simply use both, flipping back and forth as needed.

I estimate that it takes about 5 manual jumps to drill down to a particular bit of code, or (for example) to find a relationship between a table and an error code.

The problem is partially solved by some highly detailed internal documentation. But as you'd expect, the documentation has a reputation for inaccuracy, takes a lot of time to maintain, and is limited in scope.

Now, some of this documentation is good, solid technical writing. It clearly explains the intent of the code, and that's wonderful. But much of it is formulaic: it could be derived directly from the code. You can see where I'm going with this; If you've used javadoc, or pydoc, or read The Pragmatic Programmer, you'll know how easy and powerful it is to generate documentation straight from code. That's pretty much the project I was pitching.

I approached the pitch completely wrong. I assumed the discussion would hinge on the feasibility of generating any useful documentation programmatically, so I came armed with prototypes and algorithms for the report generator, justifications for using XML and XSLT instead of going straight to HTML, and so on. I was totally taken off guard when the discussion centered on the business value of the project, which I had taken for granted. I knew from working with pydoc that such tools were very helpful, but I couldn't articulate why.

There's no point in having great ideas if you don't communicate them effectively. - The Pragmatic Programmer, Tip 10.

The reason I think these tools work is because they let you focus on what your doing — the actual problem you're trying to solve. I'm going to explain this twice: first by just dumping the abstract argument I have in my head, and then with silverware. (I know you're just waiting for it!)

Lay the groundwork first, then focus on solving the problem

People are totally ineffective when they multi-task. There is a huge difference between being 70% focused on a problem, and being 90% focused. It's the difference between coming up with an elegant solution that fits into the architecture and slapping on a band-aid. If you can do any of the busy work up front, as a separate task, you should do so. Create your own focused environment. This is why mathematicians prove half a dozen lemmas before proving a theorem; they create their own problem domain to clarify the problem and provide tools to tackle it. Only then do they stand a chance of proving anything interesting. The human mind is the smallest, weakest computer we'll ever program; like programmers in olden days, we have to deal with an incredibly small transient area. Problem solving is largely a matter of making good use of that limited space.

The competent programmer is fully aware of the strictly limited size of his own skull; therefore he approaches the programming task in full humility, and among other things he avoids clever tricks like the plague. -- Edsger Dijkstra

So that's the way I store this opinion in internal memory. The problem is that most people don't really relate to mathematical proofs. How many of you are thinking, "Yes, it's just like proving lemmas! How obvious?" Let's try again:

When do you sort your silverware?

I'm getting a vision: at home, you have a "silverware drawer" where you keep your silverware neatly sorted by type: forks, spoons, sporks, etc. And you wash this silverware in a dishwasher regularly, am I right?

Ok, now a simple question. When do you sort your silverware? This question is multiple response:

1. I sort them before putting them in the dishwasher.
2. I sort them when putting them back in the drawer.
3. I don't; I keep a huge pile in the drawer, and search through them as needed.

More psychic visions... you chose 2, right? That's what I do, anyway. So let's think about why.

(1) seems a little early; silverware doesn't need to be neatly ordered while it's being washed, but this should work too. (3) doesn't work, because we'd have to do the work when we're busy cooking or eating. Even though it only takes a few seconds to select a fork, it's still a distraction.

It's not time we're saving; selecting a spoon out of a drawer is an instinctive operation, and pretty quick. But it does take our attention. We have to look at the silverware drawer, and switch our brains over to solving that trivial problem, which is the last thing we want to do when you're just starving for a sandwich or trying not to burn a creme brulee.

So you're really being quite clever here: by doing a little work ahead of time, spending 30 seconds totally focused on silverware sorting, you completely avoid task switching. You saved yourself an annoying distraction later! Smart.

Not surprisingly, we can use this strategy elsewhere too. After all, everyone already knows all the problem solving strategies; we use them every day. The trick is to simply apply those strategies to abstract things - then we can get paid for it! So the next time you find yourself being distracted from a large task by smaller ones, ask yourself: "Should I be sorting my silverware drawer?"

Back to communication

Up till now, this article has been a little schizophrenic: I've been talking about both problem solving and communication. But I've been playing a little trick on you, because actually it's entirely about communication. You see, communication is a perfect example of the kind of distracting sub-problem I've been discussing. If I'm talking about parsers, I want to be thinking about parsers: BNF grammars, yacc, ASTs, all that. But since I'm talking, I have to devote quite a bit of my brain to communication problems: clear explanations, tactful corrections, and so on.

In essence, we get distracted from what we're saying by the process of saying it.

In a formal presentation the content is laid out ahead of time, so of course you focus all your energy on communication. I'm speaking more of situations where you have to really think things through in real-time. I'm not sure how often other people get put into this situation, but I very often find myself having to analyze a technical problem and come up with solution immediately. The situation I described above is just one of many examples.

In a situation like this, concentrating on the communication itself results in style over substance; I suggest that we go the other way instead, and develop our communication skills until the communication comes naturally:

The cool thing is that we'll then be known for having great ideas, not for being a great talker. Remember, my basic thesis is that we improve efficiency when we do just one thing at a time. If that's true, then this strategy should improve the thought itself, not just its presentation. That sounds like a pretty good goal to me!

Postscript

Woah. I just wrote an article about communication as problem solving, using the problem of communicating a problem solving strategy that applies the problem of communication as an example of both the problem solving and the communication. That's so meta.