Justify My Tech

Technical book writers have it tough. They have to explain a difficult subject and make it easy enough to read. Unfortunately, tech writers often delve into "how" and not "why".

For example, Eclipse is an IDE, mostly used for writing Java code. It's got tons of functions. Most books explain how the various parts work, possibly skipping over every detail, since there is so much of it. But how many books justify why Eclipse did the things the way it did? Why did it choose perspectives? Why are there so many options?

This happens a lot. For example, suppose you're using a blogging website. You might be asked if you want to turn on "adsense" or whether you want to enable RSS feeds. It may then do so, on your command. But how many websites explain either. What is adsense, and why should you use it? What is RSS and why should you use it?

Clearly, what's happening is that the author has used it for so long that they don't even question the feature. It's there. They explain it. They don't say "this is so annoying--I wish they did it like product X". Now, to be fair, that's not that useful either because the person may never have used product X and unless you're going to devote ten pages to how that feature worked in product X so the person reading can say "oh yeah, I see why that might be a useful feature", it's not worth ranting like that.

This is a lesson in teaching. Explain why, even if you're not 100% sure why.

Java, for example, is highly verbose. Why? Presumably because they want programmers to come up with highly verbose method names. And you know what? For the most part, they do. You rarely see method names that are like gtpiod() for something like "get the penultimate index of data". This is very common in C, for instance. Java's long method names are often made bearable because IDEs like Eclipse let you type two or three characters, hit control-space for method completion, and pick the method you want.

Don't just explain how. Explain why.