hexlet-basics / hexlet-basics/exercises-typescript

Переписать вводный урок «TypeScript как второй язык»: порядок изложения и блок про установку

Open
#347 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement ready-for-human
Dominant language
TypeScript
Stars
19
Forks
89
PR merge metrics
No merged PRs in 30d

Description

This was generated by AI during triage.

Выделено из зонтичного #219 (замечание Сергея М, 2023). Относится к уроку 10-basics/20-typescript-as-a-second-language.

Проблема

Три конкретные претензии к тексту вводного урока, все три сохраняются:

  1. Порядок изложения. Сначала вводятся две группы языков, затем сразу говорится, что преимущества TypeScript возникают из-за принадлежности JavaScript к первой группе, потом объясняется первая группа, потом блоки кода, и только потом возвращение ко второй. Читатель прыгает по тексту вверх-вниз. Предложенный автором issue порядок: две группы → JavaScript динамический, что это значит → плюсы и минусы → TypeScript статический, что это значит → плюсы и минусы.
  2. Немотивированный переход. Фраза про «большие команды в десятки и сотни разработчиков» во фронтенде появляется без подготовки — до неё речь не шла ни о фронтенде, ни о размере команд.
  3. Блок про установку. Текст обещает «более простой способ», чем установка TypeScript, а на деле описывает ts-node — способ не устанавливать, а запускать без отдельной компиляции. Обещание и содержание расходятся.

Желаемый результат

Вводный урок читается линейно: каждый термин вводится до его использования, переходы мотивированы, а блок про инструменты честно называет, что чем является (компилятор tsc против запуска через ts-node).

Почему не для агента

Это переписывание теории вводного урока — самого читаемого в курсе. Нужна авторская интонация и редакторское решение о глубине (сколько говорить про плюсы/минусы динамической типизации на первом уроке). Механическая правка тут даст «текст, в котором всё верно, но никто не хочет читать».

Acceptance criteria

  • Терминов, используемых раньше, чем они введены, в уроке нет
  • Абзац про фронтенд-команды либо подготовлен предшествующим контекстом, либо убран
  • Блок про инструменты не называет ts-node «более простым способом установки»
  • ru- и en-версии синхронны по структуре
  • Полный make check проходит

Out of scope

  • Другие уроки модуля 10-basics
  • Остальные пункты #219 (разнесены отдельно или уже исправлены)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with 10-basics/20-typescript-as-a-second-language and compare its Russian and English versions. Read the current lesson against the three stated problems and acceptance criteria, then assess the needed editorial rewrite without changing other 10-basics lessons. Run make check and verify that the Russian and English structures remain synchronized.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.