FAQs happen, and have to be handled. There are four ways. A sorted commented list (I promise this won't be a rant):

Do nothing. A valued approach, and there is much to say in its favour. For an opensource hacker who's basically writing code to scratch his own itch (using the male pronoun seems safe in this context) there's no intrinsic reason to care about FAQs at all.

Variants exist. I remember a case where patch to resolve a platform-specific compile error which caused FAQs was rejected because the relevant maintainer hated macs!!!.

Write a list of FAQs which people are supposed to read. This is neat for open source projects, it allows people to enter the project by doing something easy. But it's not actually good.

A good solution would make the problem disappear. This approach allows the problem to form during in the user's use of the program, allows the problem to be put in words, but prevents (mostly) the question from being put to the maintainers. I call that a firewall to shield maintainers from their software's problems.

And, also, dealing with the FAQ lists can be beastly for mortal users — the C++ FAQ/lite must weigh three kilos when printed out.

Answer the FAQ in the documentation for the relevant feature, if any. This is one tick better than the previous, if you ask me, since a user doesn't have to look up the problem in two locations. But it still allows the problem to be formed in the user's work, and navigating the documentation to find the answer may or may not be within reach of a mortal.

A digression perhaps, but when I asked Mikrotik Support what interface wireless set disable-running-check actually does, they not only answered me, but also fixed the documentation for that setting.

Edit the code to make the FAQ go away (or at least become an occasional rather than frequently asked question). This is good. This prevents people from having problems, which is two steps better than merely answering each problem after it's bothered the user.

In the Mikrotik case, this could've been done by making the builtin tab-tab help answer the question at that point in the interface. Usually it takes more work.

No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you're likely to find. Sounds really good. But grand sentences often sound really good — better than reality even. So let's try checking that against the concrete code and documentation I personally have written. Have I written anything where the documentation describes the code better than the code itself does?

Here's what I could think of during the time it took to brew myself a pot of tea:

I have written code that was not supposed to be used, except by internal unit tests. For instance to get January 1, 1970 instead of the current time. Very useful for unit tests, but do you really want to depend on that kind of thing?

I have written documentation that described only what's common to the current and the the next major version (in Qt, I did that many, many times). Anyone who depended on the documented behaviour got a simple upgrade, anyone who read the source might get trouble, often (more…)

I am reminded of the Inmos Transputer.

That, as my older readers may still vaguely remember, was a freak processor in the eighties. It was designed for parallelism: Its fundamental design was for a computer with many transputers, not one with a single humongous blob. Each CPU was small, simple (the wikipedia page includes the complete instruction set) and linked to four other CPUs using bidirectional message-passing connections, and the design allowed vast CPU meshes with message routing and forwarding.

The thing that reminds me of the transputer is the way those links worked. When a Transputer received a message that had to be forwarded, it would prioritise communication over its own computation.

I am reminded of this because my mail is down. A great big failure happened during Christmas vacation. Then a routing mishap left me unable to take part in a video conference this morning. I am forced to prioritise my own programming over message passing, and it feels so good. Yesterday was great.

Tomorrow I shall apologise to borud about my unresponsiveness. But today, I plan to wallow in solitary hacking.

Actually I'll wait a few hours with publishing this. There's a chance someone might see it.

I quote at length from chapter four of Jef Raskin's book The humane interface:

We have looked at two interfaces, one of which will take about 5 seconds to operate and the other of which will take more than 15 seconds. [...] It is clear which of the two better satisfies the requirement. The next question that we ask is how fast an interface [...] can be. (more…)

This week, another thousand bloggers explain that patents are bad because they're used to harass, etc.

Noone seems to understand that for software patents to be meet their stated aims, it must be possible for programmers to learn something by searching for, finding and reading the relevant patent.

Wikipedia defines patents as a set of exclusive rights granted [...] to an inventor [...] in exchange for the public disclosure of an invention. That public disclosure isn't happening now: software patents aren't understandable to software developers, so the rights are granted in exchange for effectively nothing.

Wikipedia goes on to say the same thing again in different words: The word patent originates from the Latin patere, which means to lay open (i.e., to make available for public inspection).

Avoiding harassment is a start, but it's not enough. Patere necesse est.

Update: Two corollaries, obvious IMO, but... There must be something in each patent that's worth learning. Restating textbooks isn't enough. And each patent must be such that it's practically possible to work without infringing/licensing it.

I'm throwing away old books. The room with all the old bookshelves is getting a new life, and in the process of moving the books to the new shelves in a different room, some books… don't come along.

One such is Beautiful code, an anthology to support Amnesty International. I bought it for one chapter, Code in motion, in which Christopher Seiwald and Laura Wingerd elaborate on Christopher's earlier Seven pillars of pretty code (go read it, it's good).

I want to throw the book away. The other chapters are just so much filler. But I can't bring myself to throw away the figures on pages 534 and 535, those are too valuable. Must have those.

Some of the code I've written since 1992 (when my first significant contribution was accepted into an open source project) is still there, bits of it heavily used. The parts of my code that goes on working without much change shares one characteristic: It reads clearly and easily. It's well-documented, well-commented and there's hardly any nesting.

I spy a causal relationship: Truth is beauty, beauty is truth.

Some Java book I read long ago, I think it was Thinking in Java, explains that one of the benefits of Java exceptions is that you can shift error handling away from the normal path, leaving the implementation of the common case clearer and better.

Fine. There's just one catch: You have to catch the exceptions and handle the error somewhere. (more…)

Wrote colleague A to colleague B: With all due respect, suggesting anything other than an IDE today for coding is not reasonable. IntelliJ IDEA, Eclipse, NetBeans, whatever. Still running circles around your stone-tablet-tech editors ;) So, I don't understand why you would want anything less.

But B could suggest anything other, and wanted less, and he's one of the two best programmers on the team, too.

A, hm, a lively discussion ensued. What I learned: (more…)