> For the complete documentation index, see [llms.txt](https://hyfbe.gitbook.io/teacher-curriculum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hyfbe.gitbook.io/teacher-curriculum/topics/notional-machines.md). # Notional machines what does it mean to learn a programming language and runtime environment? One workable answer is [to learn a "notional machine"](https://teachtogether.tech/#s:models-notional). Just a fancy way of saying that you are comfortable using words and diagrams to explain what is happening inside of the computer at any point in your program's execution. A series of * visualizations * diagrams * refactoring techniques * vocabulary That are accurate but manageable; correct enough that you can use them to predict program state, debug your projects, and accurately translate between diagrams & code. But not so precise that you get lost in low-level implementation. An important feature of a notional machine is that they are not built on overly-familiar analogies. It should build new intuitions based on how teh programming language actually work, instead of building on old intuitions from elsewhere in life that sort-of work like the programming language. An easy danger when teaching programming is relying too heavily on approachable analogies that are not quite correct. This is especially dangerous because programming languages & computers are not like other things students have learned before. An intuitions built off of previous experience can be misleading and can lead to un-learning later on. Using a common set of visualization tools, and correct vocabulary from day 1 is super important. Building up a shared and correct understanding is only realistic when you, your peers and your coaches all discuss the same visuals with the same vocabulary. ## Topic Applied A tricky part of teaching with notional machines is related to rule #6 from [teachtogether.tech](https://teachtogether.tech/#the-rules) 1. Never hesitate to sacrifice truth for clarity. This is a fine line to walk. On one hand an approachable analogy is the definition of sacrificing truth for clarity. On the other hand, a misleading analogy will lead to less clarity in the future when a student learns something about their language that does not fit with the analogy they learned before. ## Topic Applied to JavaScript Fortunately JavaScript has a couple tools that help you to teach a JS notional machine, and more importantly allow students to continue developing theirs while not in class: * [JS Tutor](http://www.pythontutor.com/live.html#mode=edit) (everything synchronous and on the callstack) * [Loupe](http://latentflip.com/loupe/?code=!!!) (the event loop) * [Promisees](https://bevacqua.github.io/promisees) (promises) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://hyfbe.gitbook.io/teacher-curriculum/topics/notional-machines.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.