Typescript: Что вам не нравится в веб-сайте и документации TypeScript?

Страница "Типы утилит" устарела

Новые типы утилит часто пропускаются или не добавляются на страницу «Типы утилит Parameters<T> ). Мне часто приходится прибегать к просмотру lib.es5.d.ts вместо справочника.

Теги: docs

Официальная площадка TypeScript не так хороша, как альтернативы с открытым исходным кодом

https://typescript-play.js.org работает лучше, чем официальный: он охватывает несколько версий TypeScript, позволяет обмениваться большими текстами, поддерживает все флаги компилятора, а строгий режим включен по умолчанию.

Теги: playground

Отсутствие индексной страницы для примечаний к выпуску

Я бы хотел, чтобы под этим URL-адресом была индексная страница со списком всех прошлых примечаний к выпуску: https://www.typescriptlang.org/docs/handbook/release-notes . Таким образом, мы можем отслеживать обновления прошлых выпусков TypeScript.

Теги: docs , release notes

Нет глоссария названий типов

Если вы передали кому-то код вроде const a: "foo" | "bar" , возможно, вы не знаете, как назвать это типом объединения.

Это довольно низкая полоса, но когда мы начинаем говорить о типах экзистенциальных / условных / сопоставленных / и т. Д., Приятно иметь возможность перейти на страницу, которая просто пытается ее определить, но не документировать ее глубоко, чтобы вы могли получить обзор всей таксономии для этого языка

Теги: types , handbook

Нет страницы, которой можно было бы поделиться с нетехническими специалистами

Это мне нужно, чтобы сначала убедить людей, не связанных с разработкой (например, PM, нетехнических менеджеров), в чем ценность использования TypeScript. В конце концов, я написал это сам, но предпочел бы официальную

Теги: guides

Определенно типизированная документация существует вне документации TypeScript и устарела.

У проекта TypeScript должна быть собственная документация по этому поводу. Документация для Определенно Типизированного находится в:

• https://definentytyped.org
• https://github.com/DefinitiTyped/DefinitiTyped#how -can-i-влиять

Документы TS могут содержать обзор того, что это такое, почему он используется, и мы можем отказаться от официального сайта.

Теги: definitely-typed

не преподает ТС постепенно

(Отредактировано для большей читабельности) Я считаю, что документы наиболее эффективны, когда у них есть четкая «личность», для которой они предназначены. Когда были созданы эти документы, ES6 еще не существовало. Когда эти документы были созданы, вы могли изучить все TS за полдня.

Времена изменились.

Я сделал response-typescript-cheatsheet, потому что я чувствовал, что документы TS специально не предназначены для людей, которые уже знают es6, а также не хотят изучать продвинутые TS за один раз. поэтому специально нацелен на опытных JS-разработчиков, впервые пробующих TS. Нас много. Текущие документы либо «эй, вот что такое классы», либо «вот куча устрашающих дженериков на той же странице, что и наши документы по операторам типов».

в частности, вот неполный список личностей, которых следует учитывать в качестве прогрессивных учителей:

• люди, которые просто хотят использовать TS с JSDoc, без этапа сборки
• люди, которые хотят использовать TS без написания каких-либо обобщений, насколько это возможно
• люди, которые переносят кодовые базы с JS / Flow на TS
• люди, которые плохо знакомы с TS, приняли TS, но впервые видят незнакомые подробные ошибки и не знают, как с ними бороться (это аудитория " устранения неполадок ") или отказаться от этого
• люди, которые хотят публиковать библиотеки TS по сравнению с приложениями TS
• люди, которые хотят научиться использовать операторы типа
• люди, которые хотят узнать о типах утилит, которые могут им помочь
• люди, которым нужно вводить нетипизированные библиотеки (это очень сетевой эффект, и TS заинтересована в том, чтобы сделать написание .d.ts смехотворно простым и хорошо документированным, насколько это возможно)
• и в конце концов, люди, которые хотят научиться писать свою собственную логику обобщенного типа
• (возможно) люди, которые хотят писать плагины, которые должны проходить TS AST

Это все этапы на пути к внедрению TS, мы должны спланировать это и убедиться, что в документации нет обрыва, где люди падают, потому что не знают, что делать, и поэтому считают, что это слишком сложно.

Я думаю, что документы могут многое сделать, чтобы развеять миф о том, что:

• вам всегда нужна максимальная безопасность типов (не только в tsconfig, но и в выборе, который мы делаем при вводе функций)
• TS для программистов OO (да, я видел это)
• TS предназначен только для разработчиков C # / Java, которые приходят к JS и пропускают типы, это не имеет реальной ценности для разработчиков JS.
• вы должны быть в состоянии выяснить, как разрешать ошибки TS самостоятельно
• в общем, у TS есть высокая кривая обучения, чтобы начать работу

если ресурсы доступны, мы можем и должны ориентироваться на определенные крупные сообщества разработчиков, чтобы помочь их внедрению, например, для React, а также для Vue, а также для Node и так далее. Вы можете сделать это вне основной документации, например, в документации Vue проводится различие между Cookbook и Guide, уделяя особое внимание практическим примерам в контексте.

это, вероятно, такое же большое препятствие для позднего принятия TS (т.е. людей, которым требуется больше документов / инструментов / гарантий / поддержки для продажи на TS), насколько я могу себе представить.

Теги: docs

Связанная спецификация языка TypeScript полностью устарела

Прямо на главной странице вы ссылаетесь на «Спецификацию языка TypeScript».

Прочтите спецификацию на GitHub или загрузите ее в формате docx или pdf.

Однако эта спецификация полностью устарела (застряла на версии 1.8, последнее настоящее обновление - в январе 2016 года) и не поддерживается. Было бы лучше отказаться от каких-либо упоминаний о спецификации.

Теги: spec specification outdated

Виджет, похожий на игровую площадку, для примеров кода

Представьте все образцы кода в документах в виде виджета, похожего на игровую площадку, со всеми удобными всплывающими подсказками, выделениями и т. Д.

В идеале с возможностью выскакивать на полную площадку, с редактированием и просмотром сгенерированных JS / наборов.

Это, естественно, полагаться на официальную площадку TypeScript не так хорошо, как предложение

Документация по API, которая существует только в примечаниях к выпуску

Некоторые типы, например unknown , описаны только в примечаниях к выпуску , что затрудняет их обнаружение.

Теги: docs

Игровая площадка Fourslash

В / tests /ases / compiler очень много файлов, которые вместе с базовыми линиями ведут себя как загадочная темная материя. Эти мегабайты можно повторно использовать в качестве документов / демонстраций.

• заставить игровую площадку TS загружать любой файл из репозитория TS через что-то вроде: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• заставьте TS игровую площадку понимать 'Fourslash'
• добавить описательные комментарии к этим файлам

Это позволило бы кому-то ссылаться на интересные варианты синтаксиса и помочь людям повозиться и представить другие забавные тесты.

Площадка, ОБЪЯСНЯЮЩАЯ данный синтаксис TS

Нетрудно наткнуться на запутанный синтаксис TS, который действительно трудно понять. Рекурсивные дженерики, объединенные с помощью объединений и забавных индексированных типов ... Например, одно большое гнездо таких пугающих многоножек - это типизация.

Что, если бы можно было вставить кусок синтаксиса с богатым углом зрения и наблюдать подробное, удобное для восприятия человеком представление или диаграмму. Вы знаете, где вы, несомненно, можете ясно видеть, что A - это класс, а B - это тип объединения, а C - это общий параметр для D и так далее.

Начиная с наивного «многословного AST Pretty-print», это может со временем и вкладом сообщества расшириться как до более глубокого распознавания образов, так и до более богатых интерактивных визуальных элементов и UML-подобных диаграмм.

там нет поиска документации

Мне часто приходится прибегать к поиску в Google, как что-то сделать с машинописным текстом, вместо того, чтобы использовать основной документ в качестве источника истины, например, с помощью DocSearch, как в документах React.

Теги: search , exploration

Выделите общественные проекты

Это могут быть встречи, обсуждения в сообществе или книги.

Но могли бы также и более крупные программные проекты, использующие TypeScript, у которых кто-то мог бы учиться.

Теги: Community

Предоставьте инструкции по включению определенных флагов компилятора

Например, если бы я включил noImplicitReturns какими проблемами я столкнулся бы и как с ними справиться? Мы отправляем такого рода рекомендации с примечаниями к выпуску версии на то время, когда были введены эти флаги, поэтому их поиск затруднен.

Теги: tsconfig

Создайте страницу индекса ошибок компилятора

Язык ржавчины делает это , для начала довольно много усилий (в настоящее время TS имеет более тысячи ошибок), но сообщения об ошибках в tsc краткие, их наличие на сайте делает их индексируемыми поисковыми системами, улучшаемыми и с примерами кода. .

Теги: compiler

Что, если бы можно было вставить кусок синтаксиса с богатым углом зрения и наблюдать подробное, удобное для восприятия человеком представление или диаграмму?

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

type X<T extends object> = {
    [K in keyof T]: T[K]
}[keyof T]

Я мог бы сказать вам, что

X - это псевдоним типа с одним параметром типа T который ограничен значением object . При создании экземпляра с помощью T создается сопоставленный тип, где для каждой составляющей K типа keyof T значение является индексированным типом доступа T[K] . X затем создает индексированный тип доступа для этого сопоставленного типа с типом keyof T .

но было бы гораздо полезнее, и в то же время чрезвычайно трудным для кого-либо, кроме человека с практическим знанием TypeScript, сказать вам:

X получает объединение типов значений членов T .

Я думаю, что, возможно, было бы удобно иметь коллекцию «рецептов» таких шаблонов.

Страница Advanced Types - это своего рода свалка для любого неочевидного типа (я украл кучу идей TypeScript для инструмента статического анализа PHP , поэтому я часто нахожусь на этой странице).

Многие идеи связаны между собой, но это вполне можно сделать с помощью гиперссылок между страницами.

Особенно кажется, что раздел Type Guard / Type Predicate заслуживает отдельной страницы.

Руководство по написанию библиотек машинописных текстов

Я обнаружил, что отправить библиотеку, написанную на Typescript, не так просто. Множество крайних случаев, которые следует учитывать в зависимости от вашего целевого потребителя. У меня есть собственное мнение по этому поводу, которое полностью подлежит обсуждению, но документальное подтверждение официального руководства для авторов библиотеки было бы замечательно.

Теги: libraries , guidance

Мобильная навигация может быть сложной

Я не могу читать руководство по веб-сайту с мобильного телефона, что меня очень разочаровывает. Также было бы здорово, если бы у вас была возможность навигации «предыдущий / следующий» внизу страницы на каждой странице справочника.

из твита

Теги: nav

Используйте больше реальных примеров

Некоторые из текущих примеров являются слишком общими или абстрактными, с использованием соглашений об именах, основанных на буквах (A, B, C) или терминов, которые не связаны (foo, bar, baz, args, obj и т. Д.). Я надеюсь увидеть больше реальных примеров (формы, животные, продукты, пользователи) и законных вариантов использования (вызовы API, ведение журнала, обработка ошибок, форматирование данных). Это было бы особенно полезно для концепций, которые уже являются абстракциями, таких как универсальные типы и расширенные типы.

Примечание. В некоторых разделах документации эта проблема уже решена 👌🏻, но она неуместна.

Теги: examples

Библиотека примеров и передовой опыт

Покажите, как вводить различные типы функций. Подобно тому, как в lodash есть всевозможные причудливые функции, такие как выбор, расширение, сглаживание и т. Д. Опишите, как их набирать.

Библиотека, которая постепенно усложняется. Он мог бы даже прочитать больше ссылок на коммиты, которые показывают, как определенная вещь в TS используется в продакшене.

Что бы ни было построено, я надеюсь, что кому-то будет очень легко добавить примеры. Я предполагаю, что это будет справочник TS, такой как git repo.

Лучшие проекты с открытым исходным кодом обычно имеют лучшую документацию и новый пользовательский интерфейс.

Давайте сделаем TS еще более привлекательным для новых пользователей.

Лучшее описание параметров tsconfig

Текущее описание на странице параметров компилятора

• Дает очень расплывчатое описание каждой опции и того, как она влияет на компиляцию и проверку типов. Некоторые примеры могут быть действительно полезными.
• Формат таблицы оставляет небольшое пространство для описания
• Нет информации о версии TypeScript
• Алфавитный порядок бесполезен, некоторые параметры тесно связаны друг с другом, например target , module и lib или все параметры строгого типа. Их трудно понять, когда вы смотрите на них по отдельности. Вы не поймете вариант lib не поймете сначала target .
• В большинстве случаев люди используют эти параметры в файлах tsconfg, а не как параметры tsc , поэтому текущий формат может сбивать с толку новичков.
• Более подробные описания некоторых параметров разбросаны по документации, например, @types , typeRoots и types параметры описаны на странице tsconfig.json и baseUrl и paths в разрешении модуля

Это связано с предоставлением руководств по включению определенных флагов компилятора , но я думаю, что весь раздел нуждается в общем пересмотре. В настоящее время нет руководства по настройке конфигурации от начала до конца, а также нет хорошего глоссария, в котором вы могли бы узнать, что делает данная опция.

редактировать:
Не говоря уже о новых параметрах, таких как создание составных проектов, для которых нет информации в документации, и вы вынуждены собирать всю картину вместе, основываясь на примечаниях к выпуску и проблемах GitHub.

Теги: tsconfig

Собирайте документацию, блог и другие официальные ресурсы в одном месте

Если бы мы могли собрать все официальные ресурсы о TypeScript в одном месте (например, www.typescriptlang.org ), было бы здорово! 😊

Например, сообщение в блоге об анонсе v3.5 находится в другом месте ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

И примечание к выпуску v3.4 находится в другом месте:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Я считаю, что это не очень полезно и сбивает с толку разработчиков TypeScript. 😕

Теги: blog , resources

создайте tsconfig.json, заполнив форму пользовательского интерфейса с вашими предпочтениями и настройками проекта

Было бы неплохо, если бы документация содержала форму / мастер, который помогает сгенерировать tsconfig.json, который подходит для целевой среды (браузер, nodeJS), пользовательских предпочтений (настолько строгих или мягких, насколько хочет пользователь) и структуры каталогов проекта. В настоящее время параметры компилятора TS содержат несколько устаревших параметров и некоторые флаги компилятора, которые на первый взгляд выглядят так, как будто они могут делать примерно одно и то же (каковы различия между некоторыми параметрами, например, связанными с путями / каталогами / корнями). Созданный tsconfig должен соответствовать рекомендациям основной группы Microsoft TypeScript. Другой наводящий вопрос может включать:

• каков опыт команды разработчиков проекта с TypeScript (может предложить новичкам параметры компилятора, связанные с «путем миграции JS в TS», но при этом предложить все строгие параметры для «гуру TS»)
• является ли проект библиотекой или приложением (в случае библиотеки с небольшим количеством зависимостей может быть проще использовать некоторые строгие функции, такие как strictNullChecks , поэтому это может быть предложено в зависимости от опыта пользователя)
• это приложение, использующее JSX / TSX (React)
• вы используете фреймворк / библиотеку, в которой используются декораторы?
  
  
  
  • должны ли быть отправлены метаданные декораторов, чтобы они могли использоваться фреймворком / библиотекой во время выполнения (упомяните фреймворки и библиотеки, такие как Angular, Aurelia в качестве примера)
  
  

Теги: tsconfig , examples , guides , wizard , exploration

@orta Думаю, было бы здорово сделать мобильную версию игровой площадки или хотя бы адаптировать текущую. На данный момент площадка выглядит ужасно на мобильном телефоне (скриншот сделан на iPhone 7).

Хотелось бы, чтобы в области «справочника» веб-сайта был раздел, в котором говорилось бы конкретно об объектных литералах и различных способах их ввода.

Например, мне постоянно приходится гуглить что-то вроде «литерал объекта машинописного текста с любыми свойствами» или «литерал объекта машинописного текста с одним обязательным свойством и любыми другими свойствами».

И мне всегда приходится искать тип { [key: string]: any } , который на самом деле нигде не обсуждается.

Кое-что из этого обсуждается в «Интерфейсах», но это не сразу очевидно.

Увеличение типов поставщиков

Иногда при работе с определенными типами типов или определениями модулей других поставщиков я обнаруживаю, что мне нужно настроить определения:

1) Перезаписать / изменить существующее определение
2) Добавить новые методы / свойства

Мне не удалось найти документацию о том, как правильно выполнить задачу в разных сценариях. Я тоже не делал хороших заметок, когда мне нужно было сделать это самому 🐙. https://www.typescriptlang.org/docs/handbook/declaration-merging.html решает проблему для исходного кода, но я не заставил этот совет работать для сторонних типов / экспорта модулей.

Очевидно, что здорово сразу открывать PR для исправления / обновления типов в соответствующем репо, но это может занять некоторое время, чтобы снова объединиться с основной веткой, что может нарушить рабочий процесс и принудительно добавить временные преобразования any и продолжение TODO.

Теги: vendor

Документация по API компилятора

В вики есть некоторая информация об использовании Compiler API (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), но показаны только примеры того, как его использовать для достижения определенных целей. Было бы здорово иметь больше информации о стиле JSDoc, чтобы перечислить конкретные объекты и методы, которые существуют, и узнать о том, что они делают. Прямо сейчас я пытаюсь изучить API, и мне нужно взглянуть на исходный код машинописного текста, чтобы понять, что происходит.

(пожалуйста, не обращайте внимания, если это не было сделано только потому, что API еще не стабилен, как указано в вики)

Теги: compiler

Учебники, в которых основное внимание уделяется TS в сравнении с существующими языками

Многие люди переходят на TypeScript как на второй (или более) язык. Один из способов упростить изучение TypeScript - сравнить его с существующим языком, который вы уже знаете. Мы могли бы взять лучшие по популярности языки программирования

Прямо сейчас мы предполагаем, что вы знаете JS.

Теги: tutorials

Убедитесь, что он доступен по умолчанию

Убедитесь, что линтеры, такие как accessibilityinsights.io, проходят

Теги: infra

Короткие URL-адреса для игровой площадки

Было бы здорово, если бы кнопка «Поделиться» на игровой площадке TypeScript создавала короткие URL-адреса вместо того, чтобы выгружать весь исходный код в URL-адрес.

В качестве альтернативы разрешите URL-адресу содержать идентификатор github gist, который заполняет игровую площадку. например: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Теги: playground

Примеры с разными настройками (для разных вариантов использования / сценария)

Мне было сложно узнать, как я могу настроить свою кодовую базу TS и какие примеры я мог бы использовать для различных кодовых баз, поэтому было бы здорово, если бы список примеров, таких как https://github.com/microsoft/TypeScriptSamples/, был бы размещен на веб-сайте чтобы показать, как можно настроить tsconfig.json и как ему / ей следует структурировать файлы TS, чтобы они работали должным образом.

Теги: docs , examples

Нет очевидной причины, по которой документы должны быть в вики и справочнике

Страница на this в вики is_awesome_, и мне жаль, что я не нашел ее раньше. Мы должны выяснить, какие вещи должны жить в вики (тем более, что это нелегко редактировать кем-либо еще (внешние люди должны отправить PR)) и перенести другие вещи на сайт.

Сделайте лучшую навигацию между темами и заголовками

Огромные темы, такие как Руководство § Расширенные типы, имеют плохую навигацию между отдельными заголовками, нет кнопки перехода вверх . Было бы неплохо добавить плавающее меню навигации. В настоящее время сложно перейти от одного названия к другому или быстро узнать, что он нужен.

Вот хороший пример навигации, приведенный в этой книге Git о сценариях сборки: https://docs.assemblyscript.org/basics/environment

Теги: website , handbook , navigation

Редактирование кода игровой площадки для мобильных устройств

Насколько я понимаю, редактирование кода для мобильных устройств с подсветкой синтаксиса и всеми другими функциями IDE - это боль.

Тем не менее, я обнаружил, что довольно часто хочу поиграть с фрагментами кода, находясь на моем телефоне, вдали от настольного компьютера / ноутбука.

Я бы не возражал против простого поля <textarea> вместо редактора с подсветкой синтаксиса для мобильного использования.

Ошибки могут быть на другой странице, во всплывающем окне или в каком-либо другом элементе HTML.

Теги: детская площадка, мобильный, редактор кода

Документ, в котором добавлено расширение .js для модулей es6, совместимых с браузером

Нигде не упоминается, что TypeScript можно отлично использовать для создания модулей es6, которые работают в браузере, просто добавив расширение .js к имени импорта! Похоже, что эта информация существует только в этой теме:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

Не уверен, какая версия TS добавила его, но теперь работает импорт, такой как './file.js' (даже если файл на самом деле является file.ts).

Для меня это была массовая особенность ... но официально ее не существует ?!

На странице расширенных типов нет типа Omit<T, K> .

Omit<T, K> был недавно добавлен в TypeScript 3.5 , но на странице Advanced Types все еще есть следующий отказ от ответственности:

Примечание. Тип Exclude - это правильная реализация предлагаемого здесь типа Diff. Мы использовали имя Exclude, чтобы избежать нарушения существующего кода, который определяет Diff, плюс мы считаем, что это имя лучше передает семантику типа. Мы не включили опущениеtype, потому что он тривиально записывается как Pick>.

Предоставить документацию по настройке проекта для ЛИНТЕР

В рамках настройки проекта укажите, как настроить с помощью Linter, скорее всего, просто typescript-eslint, который проект должен использовать сам.

Теги: linter

Ничего не сказано о наиболее часто встречающихся ошибках или ограничениях TypeScript.

Когда вы впервые изучаете TypeScript, есть определенные шаблоны, которые никогда не будут поддерживаться в TypeScript. Один из самых простых:

const buildResult = (name?: string) => {
  const result = {};
  if (name) {
    result.name = name; // error, this property doesn't exist on {}
  }
  return result;
};

Я начал знакомить свою компанию с TypeScript, и подобные случаи всплывают часто, поэтому я начал документировать их в стиле руководства по часто задаваемым вопросам и устранению неполадок. Он быстро растет (обратите внимание, что это пока что грубо):

Создание объекта по одному за раз
Почему вы не получаете ошибок тогда, когда они вам нужны: проверка лишних свойств
Как получить доступ к необязательным свойствам, в том числе из объединений
Почему Object.keys и Object.entries не делают то, что вы хотите
Делаем фильтр filter, уменьшаем работу без ошибок
Уточнение типа теряется

Если какая-либо информация есть в документации, мне не удалось ее найти. Я понял это только через годы проб / ошибок и прочитал самые популярные вопросы на Github.

Теги: errors , troubleshooting , limitations

Предоставьте четкую документацию о том, как добавлять определения пользовательского типа.

Есть ряд библиотек, которые не включают типы и для которых нет доступного пакета @types/* . Я хотел бы иметь возможность писать свои собственные файлы объявлений для них внутри моего проекта, но, похоже, нет документации о «правильном» способе их написания и получения машинописного текста для их распознавания. Скажем, я импортирую модуль из npm. Нужно ли мне использовать declare module x ? или declare module "x" ? или использовать пространство имен? или просто экспортировать типы? Есть ли какое-то конкретное место, где мне нужно разместить эти файлы? Какие параметры конфигурации мне нужно установить? typeRoots ? types ? paths ? include ? или что? - все, что я нашел до сих пор, - это запутанные сообщения об ошибках, плохо объясненные параметры конфигурации и устаревшие вопросы SO.

Теги: docs

Отсутствие офлайн-документации

Современные базовые инструменты разработки, такие как git или npm имеют собственное подмножество команд, которые позволяют нам получить доступ к документации / справочникам в автономном режиме, например:

$ git help ls-remote
$ npm help search 

Думаю, было бы неплохо иметь такую ​​возможность (хотя TS немного отличается).
Это позволит нам исследовать документы локально с помощью команды help like без необходимости ссылаться на сайт / github и т. Д.:

$ tsc help tsc # basic CLI arguments desc
$ tsc help config # opens up html page of the tsconfig.json docs
$ tsc help v3.5 # opens up html page changelog
$ tsc help enum # finds pages containing `enum` type and hints their names/opens them up

Теги: offline , search , cli , local

В примерах нужны более различимые цвета!

Как это должно быть:

const whomstve = (name: string) => name + 'is life'

Как сейчас:

const whomstve = (name: string) => name + 'is life'

Немного синего, но это все.

Привет, ребята, я внимательно следил за этой проблемой, размышляя об общей структуре сайта и общей документации в течение последнего месяца. Теперь, когда эта проблема решена, и я немного лучше понимаю, как мне бы хотелось, чтобы документы выглядели.

Давайте попробуем просмотреть все эти моменты, основываясь на реакциях, с небольшим перетасовыванием для удобочитаемости.

Документы API иногда могут существовать только в примечаниях к выпуску

Это будет сложно, отчасти потому, что сейчас я не уверен, что живет только в примечаниях к выпуску.

Что касается языка и синтаксиса, я бы ожидал, что это будет исправлено и улучшено с выходом нового руководства, которое по-новому взглянет на язык в целом. Что касается остальной документации, я думаю, что некоторые из новых файлов Sitemap должны охватывать большинство случаев, но это все еще WIP

На сайте нет поиска

Да, я согласен, это определенно критично для нового сайта.

Сайт с закрытым кодом

Фиксированный! https://github.com/microsoft/TypeScript-website

Новая работа будет выполняться из основной ветки, но пока старый сайт доступен выше и принимает PR. Я тоже перенес сюда проблемы из репозитория TypeScript, чтобы их было легче отслеживать.

Страницы служебных программ не обновлены

Фиксированный! Частично я объединил множество PR и обновил текущее руководство от сообщества. А также убедиться, что он будет отображаться в навигаторе (а не только в веб-поиске)

Улучшено описание опций конфигурации TS.

Я начал изучать это на выходных (как мы можем гарантировать, что компилятор и веб-сайт используют один и тот же исходный источник данных для этих документов, и что веб-сайт может построить поверх этого, чтобы предоставить больше контекста)

Некоторые примеры направления на данный момент:

• мои собственные заметки с 2017 года
• Я болтал с Итаном Эрровудом @matterhorndev, чей tsconfig-ui мог бы стать основой для создания проводника TSConfig.

Детская площадка не так хороша, как альтернативы

Фиксированный! Я считаю, что это положительная ступенька в общем направлении, в котором я бы хотел видеть детскую площадку. У меня есть несколько примеров мокапов, которые обеспечивают более долгосрочную перспективу того, как должна выглядеть и ощущаться игровая площадка, чтобы сделать ее действительно лучшей в своем классе.

( нажмите для изучения фигмы )

Короткие общие URL-адреса для игровой площадки

Исправлено, см. Ниже

Нет глоссария названий типов

Я начал писать свой собственный , когда изучал компилятор - я ожидал увидеть этот канал в новом руководстве. Это также влияет на примеры игровых площадок, которые служат глоссарием примеров для некоторых из более продвинутых типов.

[детская площадка ex1, детская площадка ex2]

Не преподает постепенно TS

Это нацелено на решение в новом руководстве, процитируя некоторые из # 29288 (прокрутите до New handbook )

Написать общий документ для всех пользователей сложно, потому что аудитория TypeScript обширна, и одна из сильных сторон (и слабых сторон) текущего руководства состоит в том, что он пытается обслуживать всех сразу. У нас есть несколько разных групп разработчиков, у которых разные ожидания при изучении TypeScript, и нам нужно настроить уровень раскрытия различных концепций. Учитывая это, наша цель состоит в том, чтобы разделить справочник на три разные части:

1. Индивидуальные введения (настройка для основного руководства)
   
   
   
   1. Основной справочник (все это читают)
   
   
   2. Справочные страницы (вроде углубленных погружений / приложений)
   
   

Фактически, он имеет несколько разных отправных точек, а затем пытается обучить языку, как только вы познакомитесь с окружающей экосистемой.

Это касается всего в комментарии? Нет, только начало. Текущая карта сайта, которая у меня есть, довольно обширна, и это типы проблем, которые меня интересуют.

Я оставил некоторое пространство для маневра в моих нынешних кулинарных книгах и руководствах на карте сайта, причем поваренные книги - это то, чем мы можем поощрять большую поддержку сообщества.

Предоставить гидов

Я нашел время, чтобы начать разбираться и обновлять текущие образцы кода, которые в настоящее время находятся на веб-сайте TypeScript. Я все еще выясняю, какие образцы лучше оставить на нашей стороне, а не перенаправлять на официальную документацию (например, если проект теперь изначально поддерживает TypeScript, и у них есть свои собственные документы)

Как и в предыдущем случае, я думаю, что разделов кулинарных книг и руководств на сайте должно быть достаточно, чтобы охватить это.

Спецификация языка устарела

Да, я не знаю, смогу ли я удалить его прямо из основного репо, но на новом сайте он не будет упоминаться.

Обеспечение лучшего взаимодействия с IDE для образцов кода

Это в настоящее время входит в состав нового сайта справочника , хотя нам также придется перенести его на новый сайт. Он также обеспечивает выделение и встроенный обмен сообщениями об ошибках, что меня очень радует.

Индексная страница ошибок компилятора

Не уверен, произойдет ли это, отчасти в TypeScript есть много кодов ошибок, и они довольно регулярно меняются. К нему стоит вернуться, когда появится полностью рабочий сайт и документация, но пока это остается на втором плане.

Показать больше реальных примеров

Новое руководство пока хорошо справляется с этой задачей 👍🏾 - мы можем стремиться к тому, чтобы так и было. С остальными документами я постараюсь изменить все, что я считаю, таким образом.

Мобильная поддержка на сайте слабая

Я собираюсь использовать систему дизайна Microsoft (жидкость) для нового сайта, что должно означать, что поддержка мобильных устройств (с возможностью доступа) должна предоставляться «в основном бесплатно».

С чем-то столь же сложным, как игровая площадка, что немного сложнее, я думаю, что для мобильного телефона размером с телефон хорошо подходит мышление просмотра / исследования. Итак, у меня есть макет того, что немного ближе к опыту только для чтения:

Ознакомьтесь с улучшениями справки tsc

Я открыт для этого, но CLI машинописного текста - это на самом деле только одна команда, compile (вот почему нет необходимости в помощи по подкомандам (хотя --init как бы нарушает это))

Проконсультируем по улучшению DTS

Да, я планирую объединить определенно типизированный веб-сайт с веб-сайтом машинописного текста и объединить эти документы. Будут ли _все_ из них жить на сайте, все еще обсуждается. Есть веские доводы в пользу сохранения фактических деталей реализации вклада в определенно типизированном репозитории, в то время как высокоуровневые обзоры могут находиться на сайте.

Объедините документы / блоги / заметки о выпуске

Сложный вопрос, у меня нет ответа на заметки в блоге / выпуске. Мы используем систему ведения блогов по продуктам Microsoft со всеми остальными, и я не уверен, стоит ли переносить все это на сам веб-сайт. Мы можем представить это ближе к тому времени.

С другой стороны, я определенно хотел бы удалить такую ​​информацию из вики и оставить ее только внутри веб-сайта (где она может быть проиндексирована поиском по сайту) - я бы хотел оставить вики TypeScript специально для того, чтобы внести свой вклад в TypeScript и работа с API-интерфейсами компилятора TypeScript (например, когда вы import * as ts from “typescript” или создаете плагин языкового сервера)

Скрыть наиболее часто встречающиеся ошибки

Это относится к вышесказанному - есть действительно обширная страница

Мы можем взять это за основу и начать выводить их на основной веб-сайт вместе с вашими ответами.

Добавить подсветку синтаксиса

Да согласен, спасибо!

В общем, я думаю, что многие из них активно изучаются или над которыми мы работаем, и я открыт для получения дополнительных отзывов, поскольку мы продолжаем работать над документами!

Отличная работа, большое

Как насчет заимствования / улучшения / сотрудничества с VSCode tsconfig в редакторе Playground вместо создания отдельного?

Делает Playground лучше, а существующий опыт в VSCode уже наполовину приличный.

Я не совсем понимаю, что вы имеете в виду. Нравится функция автозаполнения схемы JSON в VS Code? Я планировал сделать это в части редактора JSON, но обзор каждой опции в виде графического интерфейса с ярлыками - полезный способ увидеть все опции и выбрать и выбрать.

@orta Когда новый справочник станет официальным справочником, будут ли URL-адреса, указывающие на разделы текущего справочника, разорваться? Или новое руководство будет по другому URL-адресу? Мне просто интересно, потому что за последние несколько лет я поместил множество ссылок на руководства в ответы SO (я уверен, что другие тоже сделали это), и было бы прискорбно, если бы все они сломались. (Есть ли лучший вопрос или место для обсуждения общих планов миграции документации?)

@orta @jcalz Интересно то же самое, у меня более 2,5 тысяч SO-ответов, найти все ответы со ссылками и обновить их все просто невозможно. В идеале ссылки с фрагментами по-прежнему будут работать и перенаправлять на новые места. При необходимости я готов помочь с составлением карты.

Да, я не верю в нарушение URI - есть несколько вариантов для изучения.

Я думаю, что он, вероятно, будет использовать новый корневой URL-адрес для справочника (например, не docs/handbook/x.html но, возможно, /handbook/x.html ), и заставит старые страницы перенаправить на их ближайший эквивалент через карту какая-то.

Я хотел бы знать, что означают все ярлыки github для этого репозитория. Некоторые из них говорят сами за себя, а другие нет.

Например, мне непонятно «Требуется предложение». Было бы полезно, если бы все ярлыки имели более длинные описания, как некоторые уже есть.

Невозможно создать ссылку на документы для _собственных_ параметров компилятора

Моя команда относительно нова в TypeScript, и поэтому наш tsconfig.json часто меняется, и часто я хочу указать людям на документацию по конкретным параметрам компилятора, то есть в форме:

https://www.typescriptlang.org/docs/handbook/compiler-options.html#strict-null-checks
(or)
https://www.typescriptlang.org/docs/handbook/compiler-options.html#strictNullChecks

Подобные ссылки не работают, но я бы хотел, чтобы они работали.

В настоящее время единственный идентификатор HTML, который я вижу на этой странице, - это # ​​compiler-options, что не так полезно, поскольку в основном находится на самом верху - однако наличие идентификатора для каждого из вариантов было бы очень полезно для привлечения людей к желаемую часть страницы.

Теги: compiler

@ Тайлер-Мерфи, мы исправили это сейчас

@ssalka - да, хороший звонок, который будет в новой документации tsconfig

-

Я собираюсь закрыть эту проблему, я повторно открою новую в будущем с той же предпосылкой, как только мы углубимся в руководство и новый сайт 👍

Машинописная площадка:
Я чувствую, что схожу с ума, но я не могу найти простой вариант «Поделиться», чтобы сохранить и поделиться своим проектом (например, для добавления в проблему с github).
Я вижу все ссылки в разделе «Экспорт», но не «Поделиться».

Машинописная площадка:
Я чувствую, что схожу с ума, но я не могу найти простой вариант «Поделиться», чтобы сохранить и поделиться своим проектом (например, для добавления в проблему с github).
Я вижу все ссылки в разделе «Экспорт», но не «Поделиться».

Пример: ссылка на игровую площадку

Новый сайт выглядит очень красиво! Однако я заметил, что этот запрос (якорные ссылки для параметров компилятора) не попал в 😕

Похоже, это будет действительно простой запрос, и он будет очень полезен для новичков. Надеюсь увидеть это в будущем обновлении!