Not all documentation is made equal. One thing that gets lost in “read the docs!” is that “the docs” are often written as a reference material and not as a textbook. References, like encyclopedias and dictionaries, have no clear starting point and assume the reader has some basic understanding of how things work, whereas when textbooks often build from basic ideas towards more complicated ones.

References work great for someone with some experience under their belt, but a total newbie learning from a reference book must either have unusual patience or (more often than not) get frustrated and quit. Patience is great and all, but it’s rather unfortunate when learning something requires unusual amounts of patience, because it often suggests that there’s a problem with the approach to learning things rather than some deep-rooted character flaw that the vast majority of new students somehow share.

This difference is especially important with computer programming, because reading the docs is really important to the learning process when it comes to programming, but it’s often incredibly frustrating to use it as a beginner. I wonder sometimes if this is why learning programming makes so many beginners feel stupid. Someone who’s been programming for years and ends up way out of their depth on a new topic can blame the docs for being confusing or the time of day or a bad night’s sleep. For beginners without the wind of previous success at their back, though, it’s very easy to think programming is simply beyond their mental abilities, whereas it might just be that they’re more-or-less trying to learn a new language just from reading the dictionary.

This message is brought to you by a silly goose who failed to have enough humility about his background knowledge in an unfamiliar sub-field of programming today!