Stackoverflow, my favorite Q&A-site, once again plans to extend its territory and create a site for software documentation. They seem to assume that their successful recipe for SO transfers nicely to this new endeavor. I am a bit sceptical – this seems to0 much like an attempt to uberize heart surgery after a successful trial run on teaching how to apply band-aids. But I might be wrong; I have a tendency to see everything new as a failure until it has proven its value because, well, this saves a lot of time. However I know that I am not wrong when I’m annoyed by one of the rationales given for the structure of this proposed expansion. Code examples seem to be one of the main features because, as the “Community Coordinator for Stack Exchange, Inc.” tries to reassure us, “a practical example is worth 1000 words of explanation“. It isn’t. If there is one thing I want you to take away from this short (I promise !) rant it’s that you should try to learn from explanations, not from examples.
It might seem a bit strange that I am so violently opposed to learning from example. After all I, back in the day, learned to write HTML by looking at the source code of websites and applying what I had learned to sites of my own. In this case learning from example worked, but that was the exception rather than the rule. The web was not very evolved, and what I saw in the source code was pretty much what the developers of the time had put there; there was little more context to have than a basic knowledge of text editors.
The same approach would not work today. You might be able to get an idea of HTML, but you would miss out on build systems, continous integration, css compilers, version management and all the other instances of infrastructure that today is behind even static websites. No HTML example will be able to demonstrate all that; you need to dig through many, many explanations to even understand why the stuff makes sense when you can just as well type HTML into notepad.
Learning by example made me use code the same way a trained monkey uses a stick. That is to say, I became very adept at certain stick-related tasks but remained largely oblivious to the possibilities inherent in the stick-wielding process. A stick is a stick, but add some context like mathematics and engineering and structural analysis and you get tools and houses and bridges and, through a long series of intermediate steps, civilization.
To take a simpler example from my own modest field of expertise, Web Analytics. If you suspect there is a problem with the number of sessions your Google Analytics records then I could tell you to check the _ga cookie, and you might or might not do this. If instead you know some of context of the http protocol and understand how http is stateless and that thus you need a mechanism to persist an identifier per device yadda yadda yadda, you not only can diagnose this particular problem yourself, you can now solve a whole class of problems that may or may not be related to analytics. That’s civilization for you.
A practical example will teach you one specific thing, in a world that requires you to know a great number of things. But it has real value only if it demonstrates a larger concept that is conveyed to you in a thousand words, or as many words as are necessary. As the old adage goes, give a man an example and he can repeat your example until he is blue in the face; explain to him how to code, and he may feed himself for a lifetime.