I open documentation for a JavaScript library and the first example already assumes I understand promises, modules and several build tools. I'm trying to solve one small problem, but every paragraph sends me to another unfamiliar concept. How do you read docs productively at that stage? I'm tempted to reproduce the smallest working example, then trace only the unfamiliar pieces that directly affect it instead of attempting a full prerequisite course first.
Reading documentation when examples assume concepts the learner has not met yet
- programming-help
- reading
- documentation
- examples
89
3 replies
That sounds like the right way to do it. I usually treat docs like a map, not a course: make the smallest example run, then stop at each unk...
That sounds like the right way to do it. I usually treat docs like a map, not a course: make the smallest example run, then stop at each unknown word and look that up separately.
Yeah, and if the docs keep sending you to promises or modules, it helps to ignore the side quests for a bit. Get one import working, get one async call working, then come back for the nicer structure later.
I do something similar with a scratch file. If an example mentions four concepts I don't know, I copy only the one I need and replace the re...
Also check the docs for a quickstart or a “minimal” section before the fancy examples. Those are usually the least annoying place to start when the main page is acting like you already built a whole app.