hexlet-basics / hexlet-basics/exercises-typescript

Редакторская вычитка теории модулей 25-types и далее

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

Nobody has claimed this yet.

documentation 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.

Выделено из зонтичного #279 (отзыв студента, 2023). Один пункт того issue — вывод clock12.render() в уроке про абстрактные классы — уже исправлен (сейчас в задании '12 : 00 AM'), остальное про качество текстов остаётся.

Проблема

Отзыв: со второй половины курса резко падает качество текста — читается как машинный перевод с английского без последующей редактуры, плюс опечатки в примерах кода. Названные студентом уроки (по нумерации code-basics.com на 2023 год) соответствуют модулю 25-types и дальше: «черепашка» — урок про литеральные типы, «json» — про иерархию типов, «кошелёк» — про вариантность, «классы» — модуль 30-classes. Про уроки после 50-го сказано «в коде примеров опечатки». В обсуждении @bondiano подтвердил: эти уроки добавлялись итеративно и редакторскую вычитку не проходили.

Конкретное расхождение, найденное при триаже сейчас (годится как первый пункт работы): в уроке 25-types/40-assignability текст говорит «при присвоении x = y; и передачи аргумента f(false);», хотя в примере функция называется len. Заодно там же пропущен пробел перед скобкой в «присваиваемостью(Assignability)».

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

Теория и задания модулей 25-types, 30-classes, 40-generics, 50-objects проходят редакторскую вычитку: связный русский текст без следов машинного перевода, идентификаторы в тексте совпадают с идентификаторами в примерах, примеры исполняются и дают заявленный вывод.

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

Вычитка теории — редакторская работа с сохранением авторской интонации, объём измеряется десятками уроков, и «переписать по-хорошему» невозможно свести к проверяемому критерию для автономного прогона. Разумный путь: вести помодульно, по одному PR на модуль, силами редактора (как это делалось для локалей других курсов).

Acceptance criteria (на модуль)

  • Все идентификаторы, упоминаемые в тексте, существуют в примерах этого же урока под тем же именем
  • Примеры кода из теории исполняются и дают вывод, указанный в комментариях
  • ru- и en-версии не расходятся по содержанию
  • make compose-description-lint, markdown-lint и полный make check проходят

Out of scope

  • Изменение структуры курса и порядка уроков (см. отдельный issue про введение union)
  • Переписывание вводного урока (отдельный issue)
  • Изменение заданий и решений учителя — только текст, если правка не требует смены задания

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 the lessons in 25-types, especially 25-types/40-assignability, then review the related lessons in 30-classes, 40-generics, and 50-objects. Check identifiers, runnable examples, and stated output in both Russian and English versions. For a module-sized change, run make compose-description-lint, markdown-lint, and make check.

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.