Typescript: Qu'est-ce que vous n'aimez pas dans le site Web et la documentation TypeScript ?

La page "Types d'utilitaires" n'est pas à jour

De nouveaux types d'utilitaires sont souvent manqués ou ne sont pas ajoutés à la page "Types d'utilitaires" du manuel (par exemple Parameters<T> ). Je dois souvent recourir à la navigation sur lib.es5.d.ts au lieu du manuel.

Mots clés : docs

Le terrain de jeu officiel TypeScript n'est pas aussi bon que les alternatives open source

https://typescript-play.js.org fait un meilleur travail que l'officiel : il couvre plusieurs versions de TypeScript, permet de partager des textes plus volumineux, il prend en charge tous les drapeaux du compilateur et le mode strict est activé par défaut.

Mots clés : playground

Absence de page d'index pour les notes de version

Je souhaite qu'il y ait une page d'index pour lister toutes les notes de version passées sous cette URL : https://www.typescriptlang.org/docs/handbook/release-notes . De cette façon, nous pouvons garder une trace des dernières mises à jour des versions sur TypeScript.

Mots clés : docs , release notes

Il n'y a pas de glossaire des noms de type

Si vous avez passé un code comme const a: "foo" | "bar" vous ne savez peut-être pas appeler cela un type d'union.

Celui-ci est une barre assez basse, mais lorsque nous commençons à parler de types existentiels/conditionnels/mappés/etc, c'est bien de pouvoir accéder à une page qui essaie juste de le définir, mais pas de le documenter en profondeur afin que vous puissiez avoir un aperçu de toute la taxonomie de cette langue

Mots clés : types , handbook

Il n'y a pas de page à partager avec des non-techniciens

Celui-ci, j'avais besoin de persuader d'abord des personnes en dehors de l'ingénierie (pensez aux PM, aux gestionnaires non techniques) de la valeur de l'utilisation de TypeScript. En fin de compte, j'ai écrit cela moi-même mais je préférerais un officiel

Mots clés : guides

La documentation définitivement typée vit en dehors des documents TypeScript et est obsolète

Le projet TypeScript devrait posséder des documents à ce sujet. La documentation de Definitely Typed réside dans :

• https://definitelytyped.org
• https://github.com/DefinitelyTyped/DefinitelyTyped#how -can-i-contribute

Les documents TS pourraient contenir un aperçu de ce que c'est, pourquoi il est utilisé et nous pouvons déprécier le site officiel

Mots clés : definitely-typed

n'enseigne pas progressivement le TS

(Modifié pour plus de lisibilité) Je pense que les documents sont plus efficaces lorsqu'ils ont un "persona" clair pour lequel ils sont destinés. Lorsque ces documents ont été créés, ES6 n'était pas encore une chose. Lorsque ces documents ont été créés, vous pouviez apprendre tout TS en un après-midi.

Les temps ont changé.

J'ai fait réagir-typescript-cheatsheet parce que je sentais que les documents TS ne servaient pas spécifiquement les personnes qui connaissaient déjà es6 et ne voulaient pas non plus apprendre les TS avancés en une seule fois. ciblant donc spécifiquement le développeur JS expérimenté essayant TS pour la première fois. nous sommes nombreux. Les documents actuels sont soit « hé, voici ce que sont les classes » ou « voici un tas de génériques effrayants sur la même page que nos documents d'opérateur de type ».

voici notamment une liste non exhaustive de personas à considérer qui pourraient servir de professeur progressif :

• les personnes qui veulent juste utiliser TS avec JSDoc, pas d'étape de construction
• les personnes qui souhaitent utiliser TS sans écrire autant que possible de génériques
• les personnes qui migrent des bases de code de JS/Flow vers TS
• les personnes qui découvrent le TS, ont adopté le TS, mais voient pour la première fois des erreurs inconnues et verbeuses et n'ont aucune idée de la façon de les gérer (il s'agit du public de « dépannage ») ou se désengagent
• les personnes qui souhaitent publier des bibliothèques TS vs des applications TS
• les personnes qui veulent apprendre à utiliser les opérateurs de type
• les personnes qui veulent en savoir plus sur les utilitaires de type qui peuvent les aider
• les personnes qui ont besoin de taper des bibliothèques non typées (c'est vraiment un effet de réseau et un intérêt de TS de rendre l'écriture .d.ts aussi ridiculement facile et bien documentée que possible)
• et aaaaaaalall the way à la fin, les gens qui veulent apprendre à écrire leur propre logique de type générique
• (peut-être) les personnes qui veulent écrire des plugins qui doivent traverser TS AST

Ce sont toutes des étapes du parcours d'adoption de TS, nous devons le cartographier et nous assurer qu'il n'y a pas de falaise dans les documents où les gens tombent parce qu'ils ne savent pas quoi faire et supposent donc que c'est trop difficile.

Je pense que les docs peuvent faire beaucoup pour aider à dissiper le mythe selon lequel :

• vous avez besoin d'une sécurité de frappe maximale à tout moment (pas seulement dans tsconfig, mais aussi dans les choix que nous faisons dans les fonctions de saisie)
• TS est pour les programmeurs OO (oui, j'ai vu ça)
• TS est uniquement pour les développeurs C#/Java qui viennent à JS et manquent des types, il n'a aucune valeur réelle pour les développeurs JS
• vous devriez être capable de résoudre vous-même les erreurs TS
• en général, que TS a une courbe d'apprentissage élevée pour commencer

si des ressources sont disponibles, nous pouvons et devons cibler de grandes communautés de développeurs spécifiques pour aider à leur adoption, par exemple pour React mais aussi Vue et aussi Node et ainsi de suite. Vous pouvez le faire à partir de la documentation principale, par exemple la documentation Vue fait une distinction entre Cookbook et Guide en se concentrant sur des exemples pratiques en contexte.

c'est probablement un obstacle aussi important à l'adoption de TS à un stade avancé (c'est-à-dire des personnes qui ont besoin de plus de documents/outils/assurance/prise en main afin d'être vendues sur TS) que je peux l'imaginer.

mots-clés : docs

La spécification du langage TypeScript lié est complètement obsolète

Directement sur la page principale, vous créez un lien vers la "Spécification du langage TypeScript".

Lisez la spécification sur GitHub ou téléchargez-la au format docx ou pdf.

Cependant, cette spécification est complètement obsolète (bloquée à la version 1.8, dernière vraie mise à jour en janvier 2016), et elle n'est pas maintenue. Il serait préférable de laisser tomber toute mention de la spécification.

Mots clés : spec specification outdated

Widget de type terrain de jeu pour des exemples de code

Présentez tous les exemples de code dans les documents dans un widget de type terrain de jeu, avec toutes les info-bulles pratiques, les faits saillants, etc.

Idéalement, avec la possibilité de sortir dans un terrain de jeu complet, avec l'édition et la visualisation des JS/dactylographies émises.

Cela reposerait naturellement sur Official TypeScript Playground n'est pas aussi bon que la suggestion d'

Documentation API qui n'existe que dans les notes de version

Certains types, par exemple unknown , ne sont documentés que dans les notes de version , ce qui les rend difficiles à découvrir.

Mots clés : docs

Aire de jeux Fourslash

Il y a énormément de fichiers dans /tests/cases/compiler qui, avec les lignes de base, se comportent comme de la matière noire cryptique. Ces mégaoctets pourraient être réutilisés comme docs/démos.

• faire en sorte que le terrain de jeu TS charge n'importe quel fichier du référentiel TS via quelque chose comme: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• faire comprendre au terrain de jeu TS 'fourslash'
• ajouter des commentaires descriptifs à ces fichiers

Cela permettrait à la fois à quelqu'un de créer un lien URL vers des cas de syntaxe intéressants et d'aider les gens à bricoler et à soumettre d'autres tests géniaux.

Terrain de jeu qui EXPLIQUE une syntaxe TS donnée

Il n'est pas difficile de tomber sur une syntaxe TS alambiquée qui est vraiment difficile à comprendre. Des génériques récursifs, combinés via des unions et des types indexés géniaux... Un grand nid de ces centipèdes effrayants est les dactylographies, par exemple.

Et si l'on était capable d'y coller un morceau de syntaxe riche en angles et d'observer une vue ou un diagramme verbeux et digestible par l'homme. Vous savez, où vous pouvez sans aucun doute voir clairement que A est une classe, et B est un type d'union, et C est un paramètre générique pour D etc.

Commençant comme une « jolie impression AST verbeuse » naïve, cela peut, avec le temps et la contribution de la communauté, s'étendre à la fois à une reconnaissance de formes plus profonde et à des visuels interactifs plus riches et des diagrammes de type UML.

il n'y a pas de recherche pour la documentation

Je dois souvent avoir recours à Google pour savoir comment faire quelque chose avec un tapuscrit plutôt que d'avoir la doc principale comme source de vérité, par exemple avec DocSearch comme sur les docs React

Mots clés : search , exploration

Mettre en valeur les projets communautaires

Cela pourrait être des choses comme des rencontres, des discussions communautaires ou des livres.

Mais il pourrait aussi y avoir des projets logiciels plus importants qui utilisent TypeScript et dont quelqu'un pourrait apprendre.

Mots clés : Community

Fournir des guides pour activer des indicateurs de compilateur spécifiques

Par exemple, si je devais activer noImplicitReturns quels types de problèmes aurais-je rencontré et comment devrais-je les gérer ? Nous envoyons ce genre de recommandations avec les notes de version de la version au moment où ces indicateurs ont été introduits, et il est donc difficile de les rechercher.

Mots clés : tsconfig

Créer une page d'index des erreurs du compilateur

Le langage rust fait cela, c'est beaucoup d'efforts pour commencer (TS a plus d'un millier d'erreurs de nos jours) mais la messagerie d'erreur dans tsc est laconique, les avoir sur un site les rend indexables par les moteurs de recherche, améliorables et avec un exemple de code .

Mots clés : compiler

Et si l'on était capable de coller un morceau de syntaxe riche en angles et d'observer une vue verbeuse digestible par l'homme ou un diagramme

Je pense que ce serait cool, mais dans certains cas, je pense qu'une explication très structurée de la façon dont un type se décompose (ce qui semble quelque peu possible à générer automatiquement) n'est pas aussi utile que de reconnaître certaines combinaisons courantes de types et de modèles qui accomplissent un objectif particulier. Par exemple, disons que je veux que quelqu'un explique ce que c'est :

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

Je _pourrais_ te dire ça

X est un alias de type avec un paramètre de type T qui est contraint à object . Lorsqu'il est instancié avec un T , il produit un type mappé, où pour chaque constituant K du type keyof T , la valeur est le type d'accès indexé T[K] . X produit alors un type d'accès indexé sur ce type mappé avec le type keyof T .

mais il serait beaucoup plus utile, et pourtant extrêmement difficile à produire par autre chose qu'un humain ayant une connaissance pratique de TypeScript, de vous dire :

X obtient l'union des types des valeurs membres de T .

Je pense qu'avoir une collection de "recettes" de modèles comme celui-ci pourrait être utile.

La page Types avancés est juste une sorte de dépotoir pour tout type non évident (j'ai volé un tas d'idées de TypeScript pour un outil d'analyse statique PHP , donc je me retrouve souvent sur cette page).

Un tas d'idées y sont liées, mais cela pourrait être fait avec des hyperliens entre les pages.

La section Type Guard/Type Predicate a particulièrement l'impression qu'elle mérite sa propre page.

Conseils pour l'écriture de bibliothèques dactylographiées

J'ai trouvé que l'expédition d'une bibliothèque écrite en Typescript n'est pas très facile. Beaucoup de cas limites à considérer en fonction de votre consommateur cible. J'ai mes propres opinions à ce sujet qui sont totalement à débattre, mais documenter les directives officielles pour les auteurs de bibliothèques serait génial.

Mots clés : libraries , guidance

La navigation mobile peut être difficile

Je ne peux pas lire le manuel du site Web depuis un mobile, ce qui est assez décevant. De plus, ce serait formidable si vous pouviez avoir une navigation précédente/suivante au bas de la page sur chaque page du manuel.

d' un tweet

Mots clés : nav

Utiliser plus d'exemples concrets

Certains des exemples actuels sont trop génériques ou abstraits, utilisant des conventions de dénomination basées sur des lettres (A, B, C) ou des termes qui ne sont pas liés (foo, bar, baz, args, obj, etc.). J'espère voir plus d'exemples concrets (formes, animaux, produits, utilisateurs) et de cas d'utilisation légitimes (appels d'API, journalisation, gestion des erreurs, formatage des données). Cela serait particulièrement utile pour les concepts qui sont déjà des abstractions, tels que les génériques et les types avancés.

Remarque : certaines parties de la documentation traitent déjà ce problème 👌🏻 mais c'est aléatoire.

Mots clés : examples

Bibliothèque d'exemples et bonnes pratiques

Montrez comment taper différents types de fonctions. Comme lodash, il a toutes sortes de fonctions fantaisistes comme choisir, étendre, aplatir, etc. Décrivez comment les taper.

Une bibliothèque qui augmente progressivement la complexité. Il aurait même pu lire plus de liens vers des commits qui montrent comment une certaine chose dans TS est utilisée en production.

Quoi qu'il en soit, j'espère qu'il sera très facile pour quelqu'un d'y ajouter des exemples. Je suppose que ce sera un manuel TS comme git repo.

Les meilleurs projets open source ont généralement la meilleure documentation et une nouvelle expérience utilisateur.

Rendons TS encore plus accueillant pour les nouveaux utilisateurs.

Meilleure description des options tsconfig

Description actuelle sur la page Options du compilateur

• Fournit une description très vague de chaque option et de son impact sur la compilation et la vérification de type. Quelques exemples pourraient être vraiment utiles.
• Le format du tableau laisse un peu d'espace de description
• Il n'y a aucune information sur la version TypeScript
• L'ordre alphabétique n'est pas utile, certaines options sont étroitement liées les unes aux autres comme target , module et lib ou toutes les options strictes. Il est difficile de bien les appréhender quand on les regarde séparément. Vous ne comprendrez pas l'option lib sans comprendre d'abord target .
• La plupart du temps, les gens utilisent ces options dans les fichiers tsconfg, pas en tant qu'options tsc , donc le format actuel peut être déroutant pour les nouveaux arrivants.
• Des descriptions plus détaillées de certaines options sont dispersées dans la documentation, par exemple les options @types , typeRoots et types sont décrites dans la page tsconfig.json et baseUrl et paths dans la résolution de module

Il est lié à Fournir des guides pour activer la suggestion d'

Éditer:
Sans parler des nouvelles options comme celle liée à la création de projets composites, pour laquelle il n'y a aucune information dans la documentation et vous êtes obligé de reconstituer l'ensemble en fonction des notes de version et des problèmes GitHub.

Mots clés : tsconfig

Rassemblez la documentation, le blog et d'autres ressources officielles en un seul endroit

Si nous pouvions rassembler toutes les ressources officielles sur TypeScript en un seul endroit (par exemple www.typescriptlang.org ), ce serait génial ! ??

Par exemple, l'article de blog sur l'annonce de la v3.5 se trouve à un autre endroit ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

Et, la note de version v3.4 est à un autre endroit :
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Je pense que ce n'est pas très utile et déroutant pour les développeurs TypeScript. ??

Mots clés : blog , resources

créez tsconfig.json en remplissant le formulaire d'interface utilisateur avec vos préférences et la configuration du projet

Ce serait bien si la documentation contenait un formulaire/assistant qui aide à générer tsconfig.json qui convient à l'environnement cible (navigateur, nodeJS), aux préférences de l'utilisateur (aussi strictes ou indulgentes que l'utilisateur le souhaite) et à la structure du répertoire du projet. Actuellement, les options du compilateur TS contiennent plusieurs options obsolètes et quelques indicateurs de compilateur, qui à première vue semblent pouvoir faire à peu près la même chose (quelles sont les différences entre certaines options, par exemple liées aux chemins/répertoires/racines). Le tsconfig généré doit respecter les meilleures pratiques de l'équipe principale de Microsoft TypeScript. Une autre question directrice pourrait inclure :

• quelle est l'expérience de l'équipe de développement du projet avec TypeScript (pourrait suggérer des options de compilateur liées au "chemin de migration JS vers TS" aux novices tout en suggérant toutes les options strictes pour les "gourous TS")
• le projet est-il une bibliothèque ou une application (dans le cas d'une bibliothèque avec peu de dépendances, il peut être plus facile d'utiliser certaines fonctionnalités strictes, telles que strictNullChecks , cela peut donc être suggéré en fonction de l'expérience de l'utilisateur)
• est l'application utilisant JSX/TSX (React)
• utilisez-vous framework/library, qui utilise des décorateurs
  
  
  
  • si les métadonnées des décorateurs sont émises, elles pourraient donc être utilisées par le framework/library au moment de l'exécution (mentionnez les frameworks et les bibliothèques, comme Angular, Aurelia par exemple)
  
  

Mots clés : tsconfig , examples , guides , wizard , exploration

@orta Je pense que ce serait génial de faire une version mobile du terrain de jeu, ou au moins d'adapter la version actuelle. Pour l'instant, le terrain de jeu a l'air affreux sur mobile (la capture d'écran est faite sur iPhone 7).

J'aurais aimé qu'il y ait une section dans la zone "manuel" du site Web qui parle spécifiquement des littéraux d'objets et des différentes manières de les taper.

Par exemple, je dois constamment rechercher sur Google quelque chose comme "littéral d'objet dactylographié avec toutes les propriétés" ou "littéral d'objet dactylographié avec une propriété requise et toutes les autres propriétés".

Et je dois toujours rechercher le type { [key: string]: any } , qui n'est vraiment discuté nulle part.

Certaines de ces choses sont parlées sur les "Interfaces" mais ce n'est pas immédiatement évident.

Augmenter les types de fournisseurs

Parfois, lorsque je travaille avec des types DefinitelyTyped ou d'autres définitions de module de fournisseur, je constate que je dois modifier les définitions pour :

1) Écraser / modifier la définition existante
2) Ajouter une nouvelle méthode/propriété

Je n'ai pas été en mesure de trouver de la documentation sur la bonne façon d'accomplir la tâche dans différents scénarios. Je n'ai pas non plus pris de bonnes notes quand j'ai eu besoin de le faire moi-même . https://www.typescriptlang.org/docs/handbook/declaration-merging.html aborde le problème du code de première partie, mais je n'ai pas fait en sorte que ce conseil fonctionne pour les types/exportations de modules tiers.

De toute évidence, il est bon d'ouvrir immédiatement les PR pour corriger / mettre à jour les types sur le référentiel correspondant, mais cela peut prendre un certain temps pour être fusionné dans la branche principale, ce qui peut perturber le flux de travail et forcer l'ajout any conversions temporaires

Mots clés : vendor

Documentation de l'API du compilateur

Le wiki contient des informations sur l'utilisation de l'API du compilateur (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) mais ne montre que des exemples d'utilisation pour atteindre certains objectifs. Ce serait bien d'avoir plus d'informations sur le style JSDoc pour répertorier les objets et méthodes spécifiques qui existent et en savoir plus sur ce qu'ils font. En ce moment, j'essaie d'apprendre l'API et j'ai besoin de regarder la source dactylographiée pour comprendre ce qui se passe.

(veuillez ignorer si cela n'a pas été fait simplement parce que l'API n'est pas encore stable comme mentionné sur le wiki)

Mots clés : compiler

Tutoriels qui se concentrent sur TS par rapport aux langues existantes

Beaucoup de gens choisissent TypeScript comme leur deuxième (ou plus) langage. Une façon de simplifier l'apprentissage de TypeScript est de le comparer à un langage existant que vous connaissez déjà. Nous pourrions prendre les meilleurs langages de programmation en termes de popularité, par exemple JS, Java, C#, PHP, C (+ CPP) et Ruby - puis proposer des didacticiels dirigés qui supposent que vous connaissez le fonctionnement de ce langage.

Pour le moment, nous supposons seulement que vous connaissez JS.

Mots clés : tutorials

Assurez-vous qu'il est accessible par défaut

Assurez-vous que les linters comme l'accessibilityinsights.io passent

Mots clés : infra

URL courtes et partageables pour le terrain de jeu

Ce serait formidable si le bouton "Partager" du terrain de jeu TypeScript produisait des URL courtes, plutôt que de vider l'intégralité du code source dans l'URL.

Vous pouvez également autoriser l'URL à contenir un ID gist github qui remplit le terrain de jeu. ex : https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Mots clés : playground

Exemples avec différents paramètres (pour différents cas d'utilisation/scénario)

J'ai trouvé difficile de savoir comment configurer ma base de code TS et quels exemples je pouvais suivre pour diverses bases de code, ce serait donc formidable si une liste d'exemples comme https://github.com/microsoft/TypeScriptSamples/ figurerait sur le site Web pour montrer comment on configurerait le tsconfig.json et comment il/elle devrait structurer les fichiers TS pour qu'ils fonctionnent comme prévu.

Mots clés : docs , examples

Aucune raison évidente pour laquelle les documents seraient dans le wiki vs manuel

La page sur this dans le wiki est_géniale_ et j'aurais aimé la trouver plus tôt. Nous devrions déterminer quel genre de choses devrait vivre dans le wiki (d'autant plus qu'il n'est pas facilement modifiable par quelqu'un d'autre (les personnes externes doivent envoyer un PR)) et déplacer les autres choses dans le site.

Améliorez la navigation entre les sujets et les titres

Des sujets énormes comme Manuel § Types avancés ont une mauvaise navigation entre les titres séparés, pas de bouton de montée non plus. Ce serait vraiment bien d'ajouter un menu de navigation flottant. Actuellement, il est difficile de passer d'un titre à l'autre ou de trouver rapidement un titre recherché.

Voici un bon exemple de navigation donné dans ce livre git Assembly Script : https://docs.assemblyscript.org/basics/environment

Mots clés : website , handbook , navigation

Édition de code de terrain de jeu adapté aux mobiles

D'après ce que je comprends, l'édition de code adaptée aux mobiles avec mise en évidence de la syntaxe et toutes les autres fonctionnalités de l'IDE est pénible.

Cependant, je me suis retrouvé à vouloir jouer assez souvent avec des extraits de code sur mon téléphone, loin d'un ordinateur de bureau/ordinateur portable.

Cela ne me dérangerait pas d'avoir un champ <textarea> simple, au lieu d'un éditeur de syntaxe en surbrillance pour une utilisation mobile.

Les erreurs pourraient éventuellement se trouver sur une autre page ou une fenêtre contextuelle ou un autre élément html.

Tags : aire de jeux, mobile, éditeur de code

Document ajoutant l'extension .js pour les modules es6 compatibles avec les navigateurs

Il n'y a aucune mention nulle part que TypeScript peut être parfaitement utilisé pour générer des modules es6 qui fonctionnent dans le navigateur en ajoutant simplement l'extension .js au nom de l'importation ! Le seul endroit où cette information semble exister est dans ce fil:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment-343610106

Je ne sais pas quelle version de TS l'a ajoutée, mais les importations telles que './file.js' fonctionnent désormais (même si le fichier est en fait un fichier.ts).

Pour moi, c'était une fonctionnalité massive... mais officiellement elle n'existe pas ?!

La page Types avancés n'inclut pas le type Omit<T, K> .

Omit<T, K> été récemment ajouté dans TypeScript 3.5 , mais la page Types avancés contient toujours la clause de non-responsabilité suivante :

Remarque : le type Exclude est une implémentation appropriée du type Diff suggéré ici. Nous avons utilisé le nom Exclude pour éviter de casser le code existant qui définit un Diff, et nous pensons que ce nom transmet mieux la sémantique du type. Nous n'avons pas inclus l'Omittapez car il est trivialement écrit comme Pick>.

Fournir une documentation de configuration de projet pour Linters

Dans le cadre de la configuration d'un projet, indiquez comment configurer avec un Linter, très probablement simplement dactylographié-eslint que le projet est censé utiliser lui-même.

Mots clés : linter

Il n'y a rien qui couvre les erreurs les plus fréquemment rencontrées ou les limitations de TypeScript.

Lorsque vous apprenez pour la première fois à TypeScript, certains modèles qui ne sont pas + ne seront jamais pris en charge dans TypeScript. L'un des plus simples :

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

J'ai commencé à introduire TypeScript dans mon entreprise, et des cas comme celui-ci apparaissent souvent, j'ai donc commencé à les documenter dans un style de guide FAQ/dépannage. Il grandit rapidement (notez que c'est dans un état approximatif):

Construire un objet une propriété à la fois
Pourquoi vous n'obtenez pas d'erreurs quand vous le souhaitez : vérification excessive des propriétés
Comment accéder aux propriétés facultatives, y compris à partir d'unions
Pourquoi Object.keys et Object.entries ne font pas ce que vous voulez
Faire un filtre de filtre, faire réduire le travail sans erreurs
Le raffinement du type est perdu

Si une de ces informations se trouve dans la doc, je n'ai pas pu la trouver. Je ne les ai compris qu'à travers des années d'essais/erreurs et en lisant les problèmes les plus liés sur Github.

Mots clés : errors , troubleshooting , limitations

Fournir une documentation claire sur la façon d'ajouter des définitions de type personnalisées

Il existe un certain nombre de bibliothèques qui n'incluent pas de types et qui n'ont pas @types/* package declare module x ? ou declare module "x" ? ou utiliser un espace de noms ? ou simplement exporter les types ? Y a-t-il un endroit spécifique où je dois mettre ces fichiers ? Quelles options de configuration dois-je définir ? typeRoots ? types ? paths ? include ? ou quoi? - tout ce que j'ai trouvé jusqu'à présent, ce sont des messages d'erreur confus, des options de configuration mal expliquées et des questions SO obsolètes.

Mots clés : docs

Manque de documentation hors ligne

Les outils de développement de base modernes comme git ou npm ont leur propre sous-ensemble de commandes qui nous permettent d'accéder à la documentation/référence hors ligne, par exemple :

$ git help ls-remote
$ npm help search 

Je pense que ce serait bien d'avoir une telle fonctionnalité (même si le TS est un peu différent).
Cela nous permettrait d'explorer les docs localement via help comme commande sans avoir besoin de se référer au site/github etc :

$ 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

Mots clés : offline , search , cli , local

Les exemples ont besoin de couleurs plus distinctives !

Comment ça devrait être :

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

Comment c'est actuellement :

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

Il y a un peu de bleu, mais c'est tout.

Salut les gens, J'ai gardé un œil sur ce problème tout en réfléchissant à la structure générale du site et à la documentation globale au cours du mois dernier. Maintenant que ce problème est résolu et que je comprends un peu mieux à quoi j'aimerais que les documents ressemblent.

Essayons de parcourir tous ces points en fonction des réactions, avec un peu de brassage pour plus de lisibilité.

Les documents d'API ne peuvent parfois exister que dans les notes de version

Celui-ci sera délicat, en partie parce que pour le moment je ne suis pas certain de ce qui ne vit que dans les notes de version.

En ce qui concerne le langage et la syntaxe, je m'attends à ce que cela soit corrigé et amélioré avec le nouveau manuel à venir qui jette un regard neuf sur l'ensemble du langage. Pour le reste de la documentation, je pense qu'une partie du nouveau plan du site devrait couvrir la plupart des cas - mais c'est toujours un WIP

Pas de recherche sur le site

Oui, je suis d'accord, celui-ci est définitivement critique pour le nouveau site.

Le site est source fermée

Fixé! https://github.com/microsoft/TypeScript-website

Le nouveau travail sortira de la branche master, mais pour l'instant l'ancien site est accessible ci-dessus et prend des PRs. J'ai également déplacé les problèmes du référentiel TypeScript vers ici, il est donc plus facile de les suivre tous.

Les pages utilitaires ne sont pas à jour

Fixé! En partie, j'ai fusionné de nombreux PR et mis à jour le manuel actuel auprès de la communauté. En plus de s'assurer qu'il apparaîtrait dans la navigation (au lieu d'une recherche sur le Web uniquement)

Descriptions des options TS Config améliorées

J'ai commencé à explorer cela au cours du week-end (comment pouvons-nous nous assurer que le compilateur et le site Web partagent la même source de données initiale pour ces documents, et que peut construire le site Web par-dessus pour fournir plus de contexte)

Quelques exemples de direction à ce jour :

• mes propres notes de 2017
• J'ai discuté avec Ethan Arrowood @matterhorndev dont tsconfig-ui pourrait être la base de la création d'un explorateur TSConfig

Le terrain de jeu n'est pas aussi bon que les alternatives

Fixé! Je considère cela comme un tremplin positif dans la direction générale que j'aimerais que le terrain de jeu soit. J'ai quelques exemples de maquettes qui offrent une perspective à plus long terme sur ce à quoi devrait ressembler le terrain de jeu pour le rendre vraiment meilleur.

( cliquez pour les explorations figma )

URL courtes partageables pour le terrain de jeu

Fixe, voir ci-dessous

Pas de glossaire des noms de type

J'ai commencé à écrire le mien au fur et à mesure que j'apprends le compilateur - je m'attendrais à voir ce flux dans le nouveau manuel. Cela affecte également les exemples de terrain de jeu, qui servent de glossaire d'exemples pour certains des types les plus avancés

[aire de jeux ex1, aire de jeux ex2]

N'enseigne pas progressivement le TS

Ceci est destiné à être traité dans le nouveau manuel, pour citer une partie de #29288 (faites défiler jusqu'à New handbook )

La rédaction d'un document général pour tous les utilisateurs est difficile car le public de TypeScript est large et l'une des forces (et faiblesses) du manuel actuel est qu'il essaie de servir tout le monde à la fois. Nous avons plusieurs groupes de développeurs différents qui ont des attentes différentes lors de l'apprentissage de TypeScript, et nous devons ajuster le niveau d'exposition des différents concepts. Compte tenu de cela, notre objectif est d'organiser le manuel en trois parties différentes :

1. Introductions personnalisées (configuration pour le manuel de base)
   
   
   
   1. Le manuel de base (tout le monde le lit)
   
   
   2. Pages de référence (un peu comme des plongées profondes/annexes)
   
   

Effectivement, il a quelques points de départ différents et essaie ensuite d'enseigner la langue une fois que vous vous êtes familiarisé avec l'écosystème environnant.

Cela répond-il à tout dans le commentaire? Non, juste le début. Le plan du site actuel que j'ai est assez complet, et ce sont les types de problèmes qui m'intéressent

J'ai laissé une certaine marge de manœuvre dans mes livres de cuisine et guides de plan de site actuels, les livres de cuisine étant quelque chose avec lequel nous pouvons encourager un plus grand soutien communautaire.

Fournir des guides

J'ai pris le temps de commencer à trier et à mettre à jour les échantillons de code actuels qui se trouvent actuellement sur le site Web de TypeScript. Je suis toujours en train de déterminer quels échantillons il vaut mieux laisser de notre côté plutôt que de rediriger vers la documentation officielle (par exemple si un projet prend désormais en charge nativement TypeScript et qu'il a sa propre documentation)

Comme ci-dessus, je pense que la section des livres de cuisine et des guides réels du site devrait être suffisante pour couvrir cela

La spécification de langue est obsolète

Oui, je ne sais pas si je peux le supprimer du référentiel principal - mais il ne sera pas mentionné sur le nouveau site.

Fournir de meilleures expériences de type IDE pour les exemples de code

Ceci est actuellement intégré au nouveau site du manuel , bien que nous devions également le transférer sur le nouveau site. Il fournit également des messages d'erreur en surbrillance et en ligne, ce qui me passionne.

Page d'index des erreurs du compilateur

Je ne sais pas si celui-ci se produira, en partie TypeScript a beaucoup de codes d'erreur et ils changent assez régulièrement. Cela vaut la peine de revenir une fois qu'il y aura un site et des documents entièrement fonctionnels, mais pour l'instant, c'est en veilleuse.

Afficher plus d'exemples concrets

Jusqu'à présent, le nouveau manuel fait du bon travail à ce sujet 👍🏾 - nous pouvons viser à ce qu'il en soit ainsi. Avec le reste de la doc, je vais essayer de changer tout ce que je vois être de cette façon.

Le support mobile sur le site est faible

J'envisage d'utiliser le système de conception Microsoft (fluide) pour le nouveau site, ce qui devrait signifier que le support mobile (avec accessibilité) devrait être « principalement gratuit »

Avec quelque chose d'aussi complexe que le terrain de jeu qui est un peu plus délicat, je pense que pour un mobile de la taille d'un téléphone, un état d'esprit de navigation / exploration est un bon choix. Donc, j'ai une maquette qui est un peu plus proche d'une expérience en lecture seule :

Explorer les améliorations de l'aide de tsc

Je suis ouvert à cela, mais la CLI dactylographiée n'est vraiment qu'une seule commande, compiler (c'est pourquoi il n'y a pas besoin d'aide sur les sous-commandes (bien que --init casse un peu cela))

Fournir des conseils sur l'amélioration du DTS

Oui, je prévois de fusionner le site Web définitivement tapé dans le site Web dactylographié et de consolider ces documents. La question de savoir si _tous_ d'entre eux vivra sur le site est encore à débattre. Il existe de bonnes raisons de conserver les détails de mise en œuvre réels de la contribution dans le référentiel définitivement typé, tandis que les aperçus de haut niveau peuvent vivre sur le site.

Consolider les docs/blogs/notes de version

Une question délicate, je n'ai pas vraiment de réponse pour le blog/les notes de version. Nous utilisons le système de blogs sur les produits Microsoft avec tout le monde, et je ne suis pas sûr que ce soit une bonne idée de déplacer tout cela sur le site Web lui-même. Nous pouvons imaginer celui-ci plus près de l'époque.

Pour simplifier, j'aimerais vraiment supprimer ce type d'informations du wiki et les laisser uniquement à l'intérieur du site Web (où elles peuvent être indexées par la recherche sur le site) - j'aimerais quitter le wiki TypeScript spécifiquement pour contribuer à TypeScript et travailler avec les API du compilateur TypeScript (par exemple lorsque vous import * as ts from “typescript” , ou créez un plugin de serveur de langage)

Couvrir les erreurs les plus courantes

Cela est lié à ce qui précède - il y a une page FAQ très complète pour ce genre de problèmes, que je viens juste de découvrir dans le wiki (3 ans après mon utilisation de TS).

Nous pouvons prendre cela comme référence et commencer à les intégrer au site Web principal avec vos réponses également.

Ajouter une coloration syntaxique

Oui d'accord, merci !

Dans l'ensemble, je pense que beaucoup d'entre eux sont activement explorés ou travaillés, et je suis ouvert à plus de commentaires alors que nous continuons à travailler sur les documents !

Super travail merci beaucoup @orta !

Que diriez-vous d'emprunter/améliorer/collaborer avec l'expérience tsconfig de VSCode dans l'éditeur Playground, au lieu d'en créer un séparé ?

Améliore le Playground et l'expérience existante dans VSCode est déjà à moitié décente.

Je ne suis pas vraiment sûr de ce que vous voulez dire. Vous aimez les fonctionnalités de schéma JSON à saisie semi-automatique dans VS Code ? J'avais prévu de l'avoir dans la partie éditeur JSON, mais un aperçu de chaque option en tant qu'interface graphique avec des étiquettes est un moyen utile de voir toutes les options et de choisir.

@orta Lorsque le nouveau manuel deviendra le manuel officiel, les URL pointant vers des sections du manuel actuel seront-elles interrompues ? Ou le nouveau manuel sera-t-il à une URL différente ? Je me demande simplement parce que j'ai mis des tas de liens de manuels dans les réponses SO au cours des dernières années (je suis sûr que d'autres l'ont fait aussi) et il serait malheureux qu'ils se cassent tous. (Y a-t-il un meilleur problème ou emplacement pour parler des plans de migration de la documentation générale ?)

@orta @jcalz Je me demandais la même chose, j'ai plus de 2,5K réponses SO, trouver toutes les réponses avec des liens et toutes les mettre à jour n'est tout simplement pas faisable. Idéalement, les liens avec des fragments fonctionneraient toujours et redirigeraient vers de nouveaux emplacements. Je suis prêt à aider avec la cartographie si nécessaire.

Oui, je ne crois pas à la rupture des URI - il y a quelques options à explorer.

Je pense que cela va probablement utiliser une nouvelle racine d'URL pour le manuel (par exemple pas docs/handbook/x.html mais peut-être /handbook/x.html ), et rediriger les anciennes pages vers leur équivalent le plus proche via une carte de une sorte.

J'aimerais savoir ce que signifient toutes les étiquettes github de ce référentiel. Certains d'entre eux sont explicites, mais d'autres ne le sont pas.

Par exemple, « Nécessite une proposition » n'est pas clair pour moi. Il serait utile que toutes les étiquettes aient des descriptions plus longues, comme certaines le font déjà.

Impossible de créer un lien vers la documentation pour les options de compilateur _spécifiques_

Mon équipe est relativement nouvelle sur TypeScript, et en tant que tel, notre tsconfig.json change fréquemment, et souvent je veux diriger les gens vers la documentation pour des options de compilateur spécifiques, c'est-à-dire sous la forme de :

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

Des liens comme celui-ci ne fonctionnent pas, mais j'aimerais qu'ils le fassent.

Actuellement, le seul identifiant HTML que je peux voir sur cette page est #compiler-options, ce qui n'est pas très utile car il est essentiellement tout en haut - avoir un identifiant pour chacune des options, cependant, serait très utile pour amener les gens à la partie souhaitée de la page.

Mots clés : compiler

@Tyler-Murphy, nous avons corrigé cela maintenant

@ssalka - ouais, bon appel qui sera dans la nouvelle documentation tsconfig

--

Je vais clore ce numéro, j'en rouvrirai un nouveau à l'avenir avec le même principe une fois que nous aurons approfondi le manuel et le nouveau site 👍

Aire de jeux dactylographiée :
J'ai l'impression de devenir fou mais je ne trouve pas une simple option 'Partager' pour enregistrer et partager mon projet (par exemple pour l'ajouter à un problème github).
Je vois tous les liens sous 'Exporter' mais pas 'Partager'.

Aire de jeux dactylographiée :
J'ai l'impression de devenir fou mais je ne trouve pas une simple option 'Partager' pour enregistrer et partager mon projet (par exemple pour l'ajouter à un problème github).
Je vois tous les liens sous 'Exporter' mais pas 'Partager'.

Exemple : lien de terrain de jeu

Le nouveau site a l'air vraiment sympa ! Cependant, j'ai remarqué que cette demande (liens d'ancrage pour les options du compilateur) ne l'a pas fait dans 😕

On dirait que ce serait une demande vraiment facile à satisfaire et serait très utile pour les nouveaux arrivants. J'espère le voir dans une future mise à jour !