It may not be honest. The author may have no authority on the subject. If you write a library, you may write a small tutorial that succinctly shows its usefulness--you certainly are the authority of your own library. In doing so you should be able to provide short examples that get the user from point A to point B, and expose enough of the API for the user to go beyond the tutorial. But after finishing a tutorial on "how to build a tile-based map" or "how to calculate the area of a polygon", i generally only expect to leave with the knowledge of one person's idea that they had for solving the issues they needed solved for their implementation, without the ability to expand on their ideas or understand the problem domain and invent new solutions. These types of articles rarely instill a good understanding of the theory they profess and instead show off just one implementation. If such a tutorial can't be copied and pasted, then one needs to write their own implementation and understand the underlying theory anyway.
The sharing of such information is in no way a bad thing, but it's not really a tutorial about how to get from A to B, is it? It's really about how the author got from A to B--her or his personal journey. The authors should therefor not spend time in theory and skip straight to implementation. What I see is the steps to reproduce an experiment.
- Observe some problem, or behaviour. (observation)
- Try to understand or describe the problem. (hypothesis)
- Try to solve the problem, based on your understanding. "If i write this code, then ... should happen" (predictions)
- Compile and run. (testing)
- Debug (go to step 2) until it works how you expect. (analysis)
That people want to share their experiments is terrific. It's how scientific communities thrive. They just aren't tutorials.
Readers of these articles may be beginners, in which case we have the blind leading the blind. The given solution may lack an idiomatic solution and its readers may not know any better. If a considerable proportion of tutorials were written by new programmers, then the experience, wisdom, and knowledge of the old programmers would be lost. I see this especially in newer languages where few or no veterans exist that maintain accessible blogs, but there is no shortage of new programmers, excited ones who want to learn everything.
Overly verbose instructions make them hard to fallow. The worst part of these blogs and articles is their verbosity. If an article wants to offer something useful, show, don't tell. Requiring long explanations of abstract concepts preliminary to understanding the fallowing code, or seeing why it's sane, indicates how little usefulness the concept really has. The author is attempting to do two things at once: teach you fundamental concepts and show you how to use them. If the author doesn't successfully give you all the knowledge you need to know, then the code is useless. For example, i would not recommend explaining how to make a binary tree using templates and std::unique_ptr by first explaining how to use templates, then how to use std::unique_ptr, then explaining binary trees.
It's pretty fucking egotistical. The article is all about the author's code, of course. It's supposed to be. There is good content in there, but the reader has to sift through the author's long paragraphs about how/why the code works. This basically gives him or her free licence to spend time talking about her or his own code. That's fine, but not when it goes into length about theory, it goes back to being dishonest.
At the end of the day, it's a good thing that we share our experiments, ideas, and beliefs with each other, but we shouldn't treat showing off our code as instructional. We should instead admit that we like showing off code for the sake of showing off code. We like to point at problems and say "look how i solved that!". Let's be more honest about it.
