This is part 2 in a series of posts in which I air my gripes and grievances (and complements!) about various kinds of software development training and reference materials.
This post is all about the official documentation and reference materials for languages, frameworks, tools, etc.
To be honest, I don’t have much negative to say here. Most of the official documentation I encounter is high quality stuff that I find myself relying on more and more.
My purpose in this post is not to complain, but to make an observation. The purpose of reference docs is to inform, which is not the same as to teach. It exists to inform you of all the things the language/framework/tool can do, but in most cases it has no interest in showing you how to use it in an application. I hesitate to call this a problem because teaching is not the point of reference docs.
Now, if you are a seasoned developer, this will not be a problem. You should be able to read through a page of reference docs and understand how to apply the material to your own projects.
But what if you are not a seasoned dev? In that case, you might have a very hard time teaching yourself from reference documentation. Without enough practical practice, you may not know why a feature is useful, or how a bit of syntax might help you. This highlights how important it is for there to be other kinds of training material beyond reference docs that focuses on how to apply this knowledge.
It also highlights how important it is for this kind of material to be written by experienced people who are not only knowledgeable, but are able to convey taht knowledge to non experts.
This is actually something that many language and tool offers try to help out with, and this is where I have a bit of mild criticism to offer. In addition to dry, raw, actual reference docs, many languages/tools/frameworks will contain other material that does intend to teach. In my experience, this material is rarely worth one’s time. Part of the problem is one of organization. This kind of material is often scattered between multiple sections of the language’s official site - Getting Started, Quick Start, Tutorials, etc. are all titles under which this kind of content is stored. It can be hard to tell what the difference is between each page. Sometimes it feels entirely arbitrary, as if all of it could be on a single page, or that the content in one category would fit better in another.
In other cases, the material might do more harm than good. I have seen many an official website with a page called Quick Start, where the honest title would be How to Learn Enough to be Dangerous in as Little Time as Possible.
Lastly, a lot of this educational material suffers from a common and extremely understandable problem. They mostly aim to teach core concepts quickly, but they quickly fill up with links and references to other, more detailed guides, or to the reference docs themselves. That “quick start” ends up turning into a deep dive.
What no one wants to admit is that sometimes it is difficult to teach someone how to use a tool/framework/language safely and effectively without doing a deep dive. This is usually due to the fact that all the individual concepts and features are so heavily intertwined that you cannot discuss one and ignore the other. Pretending that this isn’t true can do more harm than good.
Once again, I don’t blame the maintainers of these tools for the quality of their educational content. They’ve already done so much work just in making the tool available, so it feels entitled to ask for more. Beyond that, it takes more than just mastery of a subject in order to be a good teacher. You need to have the right mindset, and enough patience, among other skills. Not everyone is made out to be a teacher, nor should they be expected to. It is perfectly fine for someone to develop a programming language and not feel comfortable trying to teach someone how to use it.