Skip to content

Restructure language introduction around reader experience - #594

Merged
floitsch merged 4 commits into
masterfrom
docs/language-learning-paths
Oct 10, 2026
Merged

floitsch merged 4 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.

@floitsch
floitsch merged commit 6d0fd43 into master Oct 10, 2026
5 checks passed
@floitsch
floitsch deleted the docs/language-learning-paths branch October 10, 2026 22:04
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