Eat your own dog food

Ian Bicking has summed up pretty well what's the problem with documentation, by large: "Tell me what to do, please". Going down this road, I have some suggestions to offer.

• Every framework author should eat his own dog food. Most of them do... but 'cheat'; they sprinkle some salt over it, so it doesn't taste so bad. Sometimes they feel that it's not enough and drink a wine while using it too. Of course, they don't tell users that.


• Every framework author should do a full reinstall of its own system at least once per week. Not only that, they should try to strictly follow the documentation. And no, it's not supposed to be a simulation run. He must be willing to use whatever comes out of it as its production environment for the next week or so. But even with these rules, the main goal is not to debug the documentation or the installation procedure. The main goal is to force the programmer to stop using all those bells and whistles that he had put into his own copy and never bothered to include in the distribution. These 'hidden features' are often available only to the framework author, and its lack on the user side is a frequent cause of headaches and installation pains.

I'm sure that these simple rules can do wonders. In fact, I wonder how many people actually ever tried to live by them -- I guess the world would be a better place if they did.