Skip to content

Restructure language introduction around reader experience - #594

Open
floitsch wants to merge 3 commits into
masterfrom
docs/language-learning-paths
Open

floitsch wants to merge 3 commits into
masterfrom
docs/language-learning-paths

Conversation

@floitsch

@floitsch floitsch commented Sep 12, 2026

Copy link
Copy Markdown
Member

The language introduction mixed beginner lessons with advanced details, while the comparison page mostly translated syntax. Provide a complete primary introduction for experienced programmers and a separate, slower path for people new to programming.

  • Make “Toit for programmers” the main tour, covering syntax, functions, values and types, strings, blocks and lambdas, control flow, collections, classes and interfaces, errors, imports, and tasks.
  • Explain Toit directly and use C/C++, JavaScript, Python, and Java/Kotlin comparisons where useful. Readers do not need every comparison language, and essential content is not hidden behind fluency toggles.
  • Give blocks substantial treatment, including captured locals, block-taking methods, result and return behavior, lifetime restrictions, and the stack-based representation.
  • Keep normal examples visible and offer supplementary expandable collections for variations and edge cases.
  • Split the beginner path into three lessons: a first temperature report, lists and functions, then objects. Introduce concepts when needed and include practice at each stage.
  • Keep language-specific guides as optional entry points. Separate reference navigation from the learning paths and document the audience and example conventions for contributors.

Validation: 56 runnable examples pass toit run -Werror; the helper library in the two-file import example passes toit analyze -Werror. The production build and internal-link checks pass across 146 HTML files. New section links and git diff --check also pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant