Code Doesn't Lie

I'm learning my way through Pylons, which really is very simple (so far) but the tutorials are all wrong in different ways. Even different versions of the same one. One will reference sa.something or orm.something but never import or define 'sa' or 'orm'. Others refer to things without prefixes, but show imports "as sa" or "as orm". Yet others leave out whole sections of code to type.

That's the problem with docs, even the best of them. They lie. They may not have lied originally, but eventually they lose touch with reality and begin to say things that are not true. I don't know the editing snafus that lead to several copies of the QuickWiki tutorial all being wrong, but I know that it takes extreme vigilance to keep a document from going south. And I know that as you re-edit, you begin to be less wary. You start to read what you meant instead of what you wrote.

I'm sure this is the same case. The subject matter is quite simple, really (kudos to the team!) but I spend considerable time looking for working code samples that show the code in a form that really works. Then I can correct the incomplete instructions in the tutorial and move on. I'm working on an app of my own in parallel, so time spent researching bad docs is impairing me.

But the code tells the truth. Working, runnable, real code is reliable. If it drifts from reality it quits being working, runnable, real code. To the extent that code tells a good story, it is a better tutorial.

At this point, I think I might have been better off to start with a small app like the QuickWiki and a two-page explanation of how things fit together and the paste commands you need to make things happen.

This once again shows me how important it is to guard the readability of our code. The part that doesn't lie also should not mislead.