A Reading Order for Official Documentation

Official documentation is the best source there is for what a language actually does, and it is close to useless as a first read. It is organised for lookup: alphabetical, exhaustive, and written on the assumption that you already know which page you need. A beginner sent to it learns that the answer exists somewhere and that they cannot find it.

The course reference is the same documents arranged by the order the concepts build on each other. It is an index, not a course, and it says so: each entry is a concept with a link to the official page that defines it, in a sequence that makes sense to read through.

The citation index came first. When the written course was authored it took the main language route, and the index did not get deleted: it moved to its own address, unchanged in content and still labelled for what it is.

That is a deliberate distinction rather than an accident of history. A course and a reading index serve different readers, and merging them would have produced something that taught badly and referenced badly. The reference route exists only for languages that have a course, because for every other language the index is the language page and a second copy would be duplicate content for no reason.

• Read it in order once, following only the links whose titles you cannot already explain.
• Come back to it when a lesson summarises a rule and you want to see the rule stated exactly.
• Use it to check whether a behaviour you rely on is specified or merely typical.
• Treat an entry you cannot get through as a signal about a gap, not about the document.

Going to the primary source early is the single habit that most changes how fast somebody learns to program, and it is the one that written tutorials tend to delay. A lesson summarises; a specification defines. The difference shows up the first time your code does something the summary did not predict.

The course is written to push toward that rather than away from it. Where a lesson states a rule, the reference lists the document the rule comes from, and reading the original is treated as the normal next step rather than as advanced material.

Order, objectives and feedback. Every lesson says what you should be able to do at the end of it, which is the difference between following along and learning. Every exercise runs in a WebAssembly sandbox in your browser and tells you which assertion failed, so a wrong answer is information rather than a mark.

None of that is a criticism of documentation. It is what documentation is not for, and expecting it to teach is the reason so many people conclude they are bad at a language when they are actually reading the wrong artefact for the stage they are at.

Specifications are written for implementers, which is why they are precise and why they are hostile to a first read. Three habits make them tractable. Read the examples before the prose, because the examples are usually the shortest complete statement of what the section is about. Skip every cross-reference on the first pass, because following them produces an infinite tree and no understanding. And accept that the normative language is deliberately narrow: a sentence that reads as pedantic is usually excluding a case you have not thought of yet.

It also helps to have a reason. Reading a specification section because it is next in a list is unrewarding; reading the same section because your code did something you did not expect is memorable. That is the argument for keeping the index beside a course with exercises rather than publishing it alone.

A curated order is somebody's opinion about how concepts build, and opinions about that differ legitimately. If a sequence is not working for you, skipping ahead is not cheating: the index exists to be navigated, and coming back to a prerequisite once you have a reason to care about it is a perfectly good way to learn.

The one place order genuinely matters is where a later concept is meaningless without an earlier one rather than merely easier with it. Those dependencies are real and they are a small minority of any curriculum, which is why a reading index is a better artefact than a locked sequence.