Typescript: O que você não gosta no site e na documentação do TypeScript?

A página "Tipos de utilitários" não está atualizada

Novos tipos de utilitários são freqüentemente perdidos ou não são adicionados à página "Tipos de utilitários" do manual (por exemplo, Parameters<T> ). Freqüentemente, preciso recorrer à navegação de lib.es5.d.ts vez do manual.

Tags: docs

O Playground oficial do TypeScript não é tão bom quanto as alternativas de código aberto

https://typescript-play.js.org faz um trabalho melhor do que o oficial: cobre várias versões do TypeScript, permite compartilhar textos maiores, suporta todos os sinalizadores do compilador e o modo estrito está ativado por padrão.

Tags: playground

Falta de página de índice para notas de versão

Gostaria que houvesse uma página de índice para listar todas as notas de versão anteriores neste URL : https://www.typescriptlang.org/docs/handbook/release-notes . Dessa forma, podemos acompanhar as atualizações de versões anteriores do TypeScript.

Tags: docs , release notes

Não há um glossário de nomes de tipo

Se você passou o código de alguém como const a: "foo" | "bar" talvez não saiba como chamá-lo de tipo de união.

Este é um padrão muito baixo, mas quando começamos a falar sobre os tipos existencial / condicional / mapeado / etc, é bom poder ir para uma página que apenas tenta defini-lo, mas não documenta profundamente para que você possa ter uma visão geral de toda a taxonomia para este idioma

Tags: types , handbook

Não há uma página para compartilhar com pessoas não técnicas

Este eu precisava inicialmente persuadir as pessoas de fora da engenharia (pense em PMs, gerentes não técnicos) qual é o valor em usar o TypeScript. No final, eu mesmo escrevi isso, mas preferiria um oficial

Tags: guides

A documentação Definitivamente digitada está fora dos documentos do TypeScript e está desatualizada

O projeto TypeScript deve possuir documentos sobre isso. A documentação para Definitely Typed reside em:

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

Os documentos do TS podem conter uma visão geral do que é, por que é usado e podemos descontinuar o site oficial

Tags: definitely-typed

não ensina TS progressivamente

(Editado para maior legibilidade) Acho que os documentos são mais eficazes quando têm uma "persona" clara para a qual foram feitos. Quando esses documentos foram criados, o ES6 ainda não existia. Quando esses documentos foram criados, você poderia aprender tudo sobre TS em uma tarde.

Os tempos mudaram.

Fiz react-typescript-cheatsheet porque senti que os documentos do TS especificamente não atendiam às pessoas que já conheciam o ES6 e também não queriam aprender TS avançado de uma só vez. portanto, visando especificamente o desenvolvedor de JS experiente que está experimentando o TS pela primeira vez. há muitos de nós. Os documentos atuais são “ei, aqui estão o que são as classes” ou “aqui está um monte de genéricos de aparência assustadora na mesma página que os nossos documentos de operador de tipo”.

em particular, aqui está uma lista não exaustiva de personas a serem consideradas que poderiam servir como um professor progressista:

• pessoas que querem apenas usar TS com JSDoc, nenhuma etapa de construção
• pessoas que querem usar TS sem escrever nenhum genérico, tanto quanto possível
• pessoas que estão migrando bases de código de JS / Flow para TS
• pessoas que são novas no TS, adotaram o TS, mas veem erros estranhos e detalhados pela primeira vez e não têm ideia de como lidar com eles (este é o público de " solução de problemas ") ou optam por não fazer isso
• pessoas que desejam publicar bibliotecas de TS em vez de aplicativos de TS
• pessoas que querem aprender a usar operadores de tipo
• pessoas que querem aprender sobre utilitários de tipo que podem ajudá-los
• pessoas que precisam digitar bibliotecas não digitadas (é muito mais um efeito de rede e um interesse do TS em tornar a escrita de .d.ts o mais ridiculamente fácil e bem documentada possível)
• e aaaaaaalll no final, pessoas que querem aprender como escrever sua própria lógica de tipo genérico
• (talvez) pessoas que desejam escrever plug-ins que precisam atravessar TS AST

Todos esses são estágios na jornada de adoção do TS, devemos mapear isso e nos certificar de que não haja algum penhasco nos documentos onde as pessoas caiam porque não sabem o que fazer e, portanto, presumem que é muito difícil.

Acho que os documentos podem fazer muito para ajudar a dissipar o mito de que:

• você precisa de segurança máxima de digitação em todos os momentos (não apenas em tsconfig, mas também nas escolhas que fazemos nas funções de digitação)
• TS é para programadores OO (sim, eu já vi isso)
• TS é apenas para desenvolvedores C # / Java que vêm para JS e falham tipos, não tem valor real para desenvolvedores JS
• você deve ser capaz de descobrir como resolver erros de TS por conta própria
• em geral, esse TS tem uma alta curva de aprendizado para começar

se houver recursos disponíveis, podemos e devemos ter como alvo grandes comunidades de desenvolvimento específicas para ajudar na sua adoção, por exemplo, para React, mas também para Vue e também para Node e assim por diante. Você pode fazer isso fora dos documentos principais, por exemplo, os documentos do Vue fazem uma distinção entre Livro de Receitas e Guia com foco em exemplos práticos no contexto.

este é provavelmente um obstáculo tão grande para a adoção do TS em estágio final (ou seja, pessoas que precisam de mais documentos / ferramentas / garantia / suporte para serem vendidos no TS) quanto eu posso imaginar.

tags: docs

A especificação da linguagem Linked TypeScript está completamente desatualizada

Diretamente na página principal, você está vinculando a "TypeScript Language Specification".

Leia as especificações no GitHub ou faça o download como um docx ou pdf.

No entanto, essa especificação está completamente desatualizada (presa na versão 1.8, última atualização real em janeiro de 2016) e não é mantida. Seria melhor deixar de lado qualquer menção à especificação.

Tags: spec specification outdated

Widget parecido com Playground para amostras de código

Apresente todos os exemplos de código em documentos em um widget parecido com um playground, com todas as dicas convenientes, destaques etc.

Idealmente, com capacidade de entrar em um playground completo, com edição e visualização de JS / tipificações emitidas.

Isso naturalmente dependeria de Official TypeScript Playground não é tão bom quanto a sugestão de

Documentação da API que existe apenas nas notas de versão

Alguns tipos, por exemplo unknown , são documentados apenas nas notas de lançamento , o que os torna difíceis de descobrir.

Tags: docs

Fourslash playground

Há uma quantidade enorme de arquivos em / tests / cases / compilador que, junto com as linhas de base, se comportam como matéria escura enigmática. Esses megabytes podem ser reutilizados como documentos / demos.

• faça com que o TS playground carregue qualquer arquivo do repositório TS por meio de algo como: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• fazer TS playground entender 'fourslash'
• adicione comentários descritivos a esses arquivos

Isso permitiria que alguém fizesse um link de URL para casos de sintaxe interessantes e ajudaria as pessoas a mexer e enviar outros testes funky.

Playground que EXPLICA uma determinada sintaxe TS

Não é difícil tropeçar em uma sintaxe TS complicada que é realmente difícil de compreender. Genéricos recursivos, combinados por meio de uniões e tipos indexados descolados ... Um grande ninho dessas centopéias assustadoras são as digitações, por exemplo.

E se alguém pudesse colar um pedaço de sintaxe rica em ângulos e observar uma visão detalhada digerível por humanos ou um diagrama. Você sabe, onde você pode sem dúvida ver claramente que A é uma classe e B é um tipo de união e C é um parâmetro genérico para D e assim por diante.

Começando como uma 'impressão AST detalhada' ingênua, isso pode com o tempo e a contribuição da comunidade se expandir para um reconhecimento de padrões mais profundo e para visuais interativos mais ricos e diagramas do tipo UML.

não há busca pela documentação

Muitas vezes tenho que recorrer ao Google como fazer algo com o texto datilografado em vez de ter o documento principal como uma fonte da verdade, por exemplo, com DocSearch como nos documentos do React

Tags: search , exploration

Destacar projetos comunitários

Podem ser encontros, palestras comunitárias ou livros.

Mas também pode haver projetos de software maiores que usem TypeScript com os quais alguém possa aprender.

Tags: Community

Fornece guias para ativar sinalizadores de compilador específicos

Por exemplo, se eu ativasse noImplicitReturns que tipo de problemas eu encontraria e como devo lidar com eles? Enviamos esse tipo de recomendação com as notas de lançamento da versão para o momento em que esses sinalizadores foram introduzidos e, portanto, é difícil procurá-los.

Tags: tsconfig

Crie uma página de índice de erro do compilador

A linguagem da ferrugem faz isso é um grande esforço para começar (TS tem mais de mil erros hoje em dia), mas a mensagem de erro em tsc é concisa, tê-los em um local os torna indexáveis ​​por motores de busca, improváveis ​​e com código de exemplo .

Tags: compiler

E se alguém fosse capaz de colar um pedaço de sintaxe rica em ângulos e observar uma visão detalhada digerível por humanos ou um diagrama

Eu acho que isso seria legal, mas em alguns casos acho que uma explicação altamente estruturada de como um tipo quebra (o que parece possível de ser gerado automaticamente) não é tão útil quanto reconhecer algumas combinações comuns de tipos e padrões que realizam um objetivo particular. Por exemplo, digamos que eu queira que alguém explique o que é:

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

Eu _podia_ te dizer isso

X é um alias de tipo com um parâmetro de tipo T que está restrito a object . Quando instanciado com um T , ele produz um tipo mapeado, onde para cada constituinte K do tipo keyof T , o valor é o tipo de acesso indexado T[K] . X então produz um tipo de acesso indexado naquele tipo mapeado com o tipo keyof T .

mas seria muito mais útil, e ainda assim extraordinariamente difícil de produzir por qualquer coisa que não fosse um ser humano com conhecimento prático de TypeScript, dizer a você:

X obtém a união dos tipos de valores de membros de T .

Acho que talvez seja útil ter uma coleção de “receitas” de padrões como essa.

A página Tipos avançados é apenas uma espécie de lixeira para qualquer tipo não óbvio (eu roubei um monte de ideias do TypeScript para uma ferramenta de análise estática de PHP , então me encontro muito nessa página).

Muitas das ideias estão interligadas, mas isso poderia ser feito com hiperlinks entre as páginas.

A seção Type Guard / Type Predicate parece que merece sua própria página.

Orientação para escrever bibliotecas de texto digitado

Descobri que enviar uma biblioteca escrita em Typescript não é muito fácil. Muitos casos extremos a serem considerados, dependendo do seu consumidor-alvo. Tenho minhas próprias opiniões sobre isso que estão totalmente abertas para debate, mas documentar a orientação oficial para autores de bibliotecas seria incrível.

Tags: libraries , guidance

A navegação móvel pode ser difícil

Não consigo ler o manual do site no celular, o que é muito decepcionante. Também seria ótimo se você pudesse ter a navegação anterior / seguinte na parte inferior da página em cada página do manual.

de um tweet

Tags: nav

Use mais exemplos do mundo real

Alguns dos exemplos atuais são excessivamente genéricos ou abstratos, usando convenções de nomenclatura baseadas em letras (A, B, C) ou termos que não são relacionáveis ​​(foo, bar, baz, args, obj, etc). Espero ver mais exemplos do mundo real (formas, animais, produtos, usuários) e casos de uso legítimos (chamadas de API, registro, tratamento de erros, formatação de dados). Isso seria especialmente útil para conceitos que já são abstrações, como Genéricos e Tipos avançados.

Nota: Algumas áreas da documentação já tratam desse problema 👌🏻 mas é um acerto e erro.

Tags: examples

Biblioteca de exemplo e melhores práticas

Mostre como digitar diferentes tipos de funções. Como o lodash, tem todos os tipos de funções sofisticadas, como escolher, estender, achatar, etc. Descreva como digitá-los.

Uma biblioteca que aumenta a complexidade de forma incremental. Poderia até ter lido mais links para commits que mostram como uma certa coisa no TS é usada na produção.

Seja o que for que acabe sendo construído, espero que seja muito fácil para alguém adicionar exemplos. Presumo que seja um manual de TS como o git repo.

Os melhores projetos de código aberto geralmente têm a melhor documentação e a nova experiência do usuário.

Vamos tornar o TS ainda mais acolhedor para novos usuários.

Melhor descrição das opções de tsconfig

Descrição atual na página de opções do compilador

• Fornece uma descrição muito vaga de cada opção e como ela afeta a compilação e a verificação de tipo. Alguns exemplos podem ser realmente úteis.
• O formato da tabela deixa um pequeno espaço de descrição
• Não há informações sobre a versão do TypeScript
• A ordem alfabética não é útil, algumas opções estão intimamente relacionadas entre si, como target , module e lib ou todas as opções semelhantes. É difícil entendê-los bem quando você olha para eles separadamente. Você não entenderá lib option sem entender target primeiro.
• Na maioria das vezes, as pessoas usam essas opções em arquivos tsconfg, não como tsc options, portanto, o formato atual pode ser confuso para os iniciantes.
• Descrições mais detalhadas de algumas opções estão espalhadas pela documentação, por exemplo, @types , typeRoots e types opções são descritas na página tsconfig.json e baseUrl e paths na resolução do módulo

Ele está conectado com os guias do Provide para ativar sugestões

editar:
Sem mencionar as novas opções, como a relacionada à construção de projetos compostos, para os quais não há informações nos documentos e você é forçado a montar toda a imagem com base nas notas de lançamento e nos problemas do GitHub.

Tags: tsconfig

Reúna documentação, blog e outros recursos oficiais em um só lugar

Se pudéssemos reunir todos os recursos oficiais sobre o TypeScript em um só lugar (por exemplo, www.typescriptlang.org ), seria incrível! 😊

Por exemplo, a postagem do blog sobre o anúncio da v3.5 está em outro lugar ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

E a nota de versão v3.4 está em outro lugar:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Acho que isso não é muito útil e confuso para desenvolvedores de TypeScript. 😕

Tags: blog , resources

crie tsconfig.json preenchendo o formulário da IU com suas preferências e configuração do projeto

Seria bom se a documentação contivesse um formulário / assistente que ajudasse a gerar tsconfig.json adequado ao ambiente de destino (navegador, nodeJS), preferências do usuário (tão estritas ou tolerantes quanto o usuário quiser) e estrutura de diretório do projeto. Atualmente, as Opções do Compilador TS contêm várias opções obsoletas e alguns sinalizadores de compilador, que à primeira vista parecem que podem fazer praticamente a mesma coisa (quais são as diferenças entre algumas opções, por exemplo, relacionadas a caminhos / dirs / raízes). O tsconfig gerado deve seguir as práticas recomendadas da equipe principal do Microsoft TypeScript. Outras questões de orientação podem incluir:

• qual é a experiência da equipe de desenvolvimento do projeto com TypeScript (pode sugerir opções de compilador relacionadas a "caminho de migração de JS para TS" para iniciantes, enquanto sugere todas as opções estritas para "gurus de TS")
• é o projeto uma biblioteca ou aplicativo (no caso de uma biblioteca com poucas dependências, pode ser mais fácil usar alguns recursos restritos, como strictNullChecks , então pode ser sugerido dependendo da experiência do usuário)
• é o aplicativo que usa JSX / TSX (React)
• você está usando framework / biblioteca, que usa decoradores
  
  
  
  • os metadados dos decoradores devem ser emitidos, para que possam ser usados ​​pelo framework / biblioteca em tempo de execução (mencione frameworks e bibliotecas, como Angular, Aurelia como exemplo)
  
  

Tags: tsconfig , examples , guides , wizard , exploration

@orta Eu acho que seria incrível fazer uma versão mobile do playground, ou pelo menos adaptar a atual. A partir de agora, o playground parece horrível no celular (a captura de tela é feita no iPhone 7).

Gostaria que houvesse uma seção na área "manual" do site que falasse especificamente sobre literais de objeto e as várias maneiras de digitá-los.

Por exemplo, estou constantemente tendo que pesquisar no Google algo como "literal de objeto de texto digitado com quaisquer propriedades" ou "literal de objeto de texto digitado com uma propriedade necessária e quaisquer outras propriedades".

E eu sempre tenho que procurar o tipo { [key: string]: any } , que não é realmente discutido em lugar nenhum.

Algumas dessas coisas são faladas nas "Interfaces", mas isso não é imediatamente óbvio.

Aumentando os tipos de fornecedores

Às vezes, ao trabalhar com tipos DefinitelyTyped ou outras definições de módulo de fornecedor, acho que preciso ajustar as definições para:

1) Substituir / modificar a definição existente
2) Adicionar novos métodos / propriedades

Não consegui encontrar documentação sobre a maneira adequada de realizar a tarefa em diferentes cenários. Eu também não fiz boas anotações quando precisei fazer isso sozinho 🐙. https://www.typescriptlang.org/docs/handbook/declaration-merging.html aborda o problema do código original, mas não fiz esse conselho funcionar para tipos / exportações de módulo de terceiros.

Obviamente, é ótimo abrir PRs imediatamente para corrigir / atualizar os tipos no repo correspondente, mas pode demorar um pouco para ser mesclado de volta ao branch mestre, o que pode interromper o fluxo de trabalho e forçar a adição de any conversões temporárias e um acompanhamento TODO.

Tags: vendor

Documentação da API do compilador

O wiki tem algumas informações sobre como usar a API do compilador (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), mas mostra apenas exemplos de como usá-la para atingir certos objetivos. Seria ótimo ter mais informações de estilo JSDoc para listar os objetos e métodos específicos que existem e aprender sobre o que eles fazem. No momento, estou tentando aprender a API e preciso examinar o código-fonte do texto digitado para descobrir o que está acontecendo.

(ignore se isso não foi feito apenas porque a API ainda não está estável conforme mencionado no wiki)

Tags: compiler

Tutoriais que enfocam o TS em comparação com as línguas existentes

Muitas pessoas vêm para o TypeScript como sua segunda (ou mais) linguagem. Uma maneira de simplificar o aprendizado do TypeScript é compará-lo a uma linguagem existente que você já conhece. Poderíamos pegar as principais linguagens de programação por popularidade, por exemplo, JS, Java, C #, PHP, C (+ CPP) e Ruby - então, direcionamos tutoriais que presumem que você tem o conhecimento de como essa linguagem funciona.

No momento, apenas pressupomos que você conhece JS.

Tags: tutorials

Certifique-se de que esteja acessível por padrão

Certifique-se de que linters como accessibilityinsights.io passem

Tags: infra

URLs curtos e compartilháveis ​​para o playground

Seria ótimo se o botão "Compartilhar" do playground do TypeScript produzisse URLs curtos, em vez de despejar todo o código-fonte no URL.

Como alternativa, permita que o URL contenha um github gist ID que preenche o playground. por exemplo: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Tags: playground

Exemplos com diferentes configurações (para diferentes casos de uso / cenário)

Achei complicado saber como eu poderia configurar minha base de código TS e quais exemplos eu poderia seguir para várias bases de código, então seria ótimo se uma lista de exemplos como https://github.com/microsoft/TypeScriptSamples/ aparecesse no site para mostrar como alguém configuraria o tsconfig.json e como ele / ela deve estruturar os arquivos TS para funcionar como pretendido.

Tags: docs , examples

Nenhuma razão óbvia para os documentos estarem no wiki vs manual

A página this no wiki é_awesome_ e eu gostaria de tê-la encontrado antes. Devemos descobrir que tipo de coisas devem estar no wiki (especialmente porque não é facilmente editável por ninguém (o pessoal externo tem que enviar um PR)) e mover as outras coisas para o site.

Faça melhor navegação entre tópicos e títulos

Tópicos enormes, como Handbook § Tipos avançados, apresentam uma navegação deficiente entre títulos separados, também não há botão de subir . Seria muito bom adicionar um menu de navegação flutuante. Atualmente é difícil pular de um título para outro ou descobrir rapidamente o que deseja.

Aqui está um bom exemplo de navegação dado neste livro git do Assembly Script: https://docs.assemblyscript.org/basics/environment

Tags: website , handbook , navigation

Edição de código de playground compatível com dispositivos móveis

Pelo que entendi, a edição de código compatível com dispositivos móveis com destaque de sintaxe e todos os outros recursos do IDE é uma dor.

No entanto, tenho vontade de brincar com trechos de código enquanto estou no telefone, longe de um desktop / laptop, com bastante frequência.

Eu não me importaria com um campo <textarea> simples, em vez de um editor com destaque de sintaxe para uso móvel.

Os erros podem estar em outra página, em um pop-up ou em algum outro elemento html.

Tags: playground, celular, editor de código

Documento que adiciona a extensão .js para módulos es6 compatíveis com navegador

Não há nenhuma menção de que o TypeScript pode ser usado perfeitamente bem para gerar módulos es6 que funcionam no navegador simplesmente adicionando a extensão .js ao nome da importação! O único lugar onde esta informação parece existir é neste tópico:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

Não tenho certeza de qual versão do TS o adicionou, mas importações como './file.js' agora funcionam (mesmo se o arquivo for realmente file.ts).

Para mim, isso foi um recurso enorme ... mas oficialmente não existe ?!

A página de Tipos avançados não inclui Omit<T, K> type.

Omit<T, K> foi adicionado recentemente ao TypeScript 3.5 , mas a página Tipos avançados ainda tem a seguinte isenção de responsabilidade:

Nota: O tipo Exclude é uma implementação adequada do tipo Diff sugerido aqui. Usamos o nome Exclude para evitar quebrar o código existente que define um Diff, além disso, achamos que o nome transmite melhor a semântica do tipo. Não incluímos o Omitdigite porque é trivialmente escrito como Pick>.

Fornece documentação de configuração do projeto para Linters

Como parte da configuração de um projeto, inclua como configurar com um Linter, muito provavelmente apenas typescript-eslint que o projeto supostamente deve estar usando.

Tags: linter

Não há nada que cubra os erros mais comuns ou as limitações do TypeScript.

Quando você está aprendendo o TypeScript pela primeira vez, há certos padrões que não são + nunca serão suportados no TypeScript. Um dos mais simples:

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

Comecei a apresentar o TypeScript à minha empresa e casos como este surgem muito, então comecei a documentá-los em um guia de estilo de FAQ / solução de problemas. Está crescendo rapidamente (observe que está em um estado aproximado):

Construindo um objeto, uma propriedade de cada vez
Por que você não está recebendo erros quando os deseja: verificação de propriedade em excesso
Como acessar propriedades opcionais, inclusive de sindicatos
Por que Object.keys e Object.entries não fazem o que você quer
Fazendo filtro de filtro, reduzindo trabalho sem erros
Perda de refinamento de tipo

Se alguma dessas informações estiver nos documentos, não consegui localizá-la. Eu só entendi isso por meio de anos de tentativa / erro e lendo os problemas mais relacionados no Github.

Tags: errors , troubleshooting , limitations

Fornece documentação clara sobre como adicionar definições de tipo personalizadas

Existem várias bibliotecas que não incluem tipos e que não têm um pacote @types/* disponível. Eu gostaria de poder escrever meus próprios arquivos de declaração para eles dentro do meu projeto, mas não parece haver nenhuma documentação sobre a maneira 'certa' de escrevê-los e obter um texto digitado para reconhecê-los. Digamos que estou importando um módulo do npm. Preciso usar declare module x ? ou declare module "x" ? ou usar um namespace? ou apenas exportar os tipos? Existe um local específico onde devo colocar esses arquivos? Quais opções de configuração eu preciso definir? typeRoots ? types ? paths ? include ? ou o que? - tudo o que encontrei até agora são mensagens de erro confusas, opções de configuração mal explicadas e questões SO desatualizadas.

Tags: docs

Falta de documentação offline

Ferramentas de desenvolvimento básicas modernas como git ou npm têm seu próprio subconjunto de comandos que nos permitem acessar documentação / referência offline, por exemplo:

$ git help ls-remote
$ npm help search 

Acho que seria bom ter esse recurso (embora o TS seja um pouco diferente).
Isso nos permitiria explorar documentos localmente por meio do comando help like sem a necessidade de consultar o 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

Tags: offline , search , cli , local

Os exemplos precisam de algumas cores para distinguir melhor!

Como deve ser:

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

Como está atualmente:

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

Tem um pouco de azul, mas é só isso.

Olá pessoal, estou de olho neste problema enquanto penso sobre a estrutura geral do site e a documentação geral no mês passado. Agora que esse problema foi resolvido, tenho um pouco mais de entendimento sobre como gostaria que os documentos fossem.

Vamos tentar examinar todos esses pontos com base nas reações, com um pouco de embaralhamento para facilitar a leitura.

Os documentos da API às vezes só podem existir nas notas de lançamento

Este será complicado, em parte porque agora não tenho certeza do que vive apenas nas notas de lançamento.

Com relação à linguagem e sintaxe, espero que isso seja corrigido e melhorado com o novo manual que está por vir, que está dando uma nova olhada em toda a linguagem. Para o resto da documentação, acho que alguns dos novos mapas do site devem cobrir a maioria dos casos - mas ainda é um WIP

Sem pesquisa no site

Sim, concordo, este é definitivamente crítico para o novo site.

O site é de código fechado

Fixo! https://github.com/microsoft/TypeScript-website

O novo trabalho sairá do branch master, mas por enquanto o site antigo está acessível acima e recebendo PRs. Também movi problemas do repositório TypeScript para aqui, então é mais fácil controlar todos eles.

Páginas do utilitário não atualizadas

Fixo! Em parte, mesclei vários RPs e atualizei o manual atual da comunidade. Além de garantir que ele apareça no painel de navegação (em vez de apenas em uma pesquisa na web)

Descrições de opções de configuração de TS aprimoradas

Comecei a explorar isso no fim de semana (como podemos garantir que o compilador e o site compartilhem a mesma fonte de dados inicial para esses documentos, e o que o site pode construir em cima disso para fornecer mais contexto)

Alguns exemplos de direção até agora:

• minhas próprias notas de 2017
• Tenho conversado com Ethan Arrowood @matterhorndev cujo tsconfig-ui pode ser a base para a criação de um explorador TSConfig

Playground não é tão bom quanto alternativas

Fixo! Eu considero isso um ponto de partida positivo na direção geral que eu gostaria que fosse o playground. Eu tenho alguns exemplos de maquetes que fornecem uma perspectiva de longo prazo sobre como o Playground deve ser e sentir para torná-lo realmente o melhor.

( clique para explorar figma )

URLs curtos compartilháveis ​​para playground

Corrigido, veja abaixo

Nenhum glossário de nomes de tipo

Comecei a escrever meu próprio , conforme aprendo o compilador - espero ver este feed no novo manual. Também afeta os exemplos de playground, que servem como um glossário de exemplos para alguns dos tipos mais avançados

[playground ex1, playground ex2]

Não ensina TS progressivamente

Isso deve ser abordado no novo manual, para citar alguns dos # 29288 (vá até New handbook )

Escrever um documento geral para todos os usuários é difícil porque o público do TypeScript é amplo e um dos pontos fortes (e fracos) do manual atual é que ele tenta servir a todos ao mesmo tempo. Temos vários grupos diferentes de desenvolvedores que têm expectativas diferentes ao aprender TypeScript e precisamos ajustar o nível de exposição de diferentes conceitos. Diante disso, nosso objetivo é organizar o manual em três partes diferentes:

1. Introduções personalizadas (configuração para o manual principal)
   
   
   
   1. O manual básico (todo mundo lê isso)
   
   
   2. Páginas de referência (como mergulhos profundos / apêndices)
   
   

Efetivamente, ele tem alguns pontos de partida diferentes e, em seguida, tenta ensinar o idioma assim que você se familiarizar com o ecossistema circundante.

Isso aborda tudo no comentário? Não, apenas o começo. O mapa do site atual que tenho é muito extenso, e esses são os tipos de problemas nos quais estou interessado

Eu deixei algum espaço de manobra em meus atuais livros de receitas e guias do mapa do site, com livros de receitas sendo algo com o qual podemos encorajar mais apoio da comunidade.

Fornecer Guias

Dediquei um tempo para começar a classificar e atualizar os exemplos de código atuais que estão atualmente no site do TypeScript. Ainda estou descobrindo quais amostras devem ser deixadas do nosso lado em vez de redirecionar para a documentação oficial (por exemplo, se um projeto agora suporta TypeScript nativamente e eles têm seus próprios documentos)

Como acima, acho que a seção de livros de receitas e guias reais do site deve ser suficiente para cobrir isso

As especificações do idioma estão desatualizadas

Sim, não sei se posso removê-lo imediatamente do repositório principal - mas não será mencionado no novo site.

Fornece melhores experiências semelhantes às de IDE para exemplos de código

No momento, isso está incluído no novo site de manual , embora tenhamos que transferi-lo para o novo site também. Ele também fornece mensagens de erro em linha e de destaque, o que me deixa muito entusiasmado.

Página de índice de erro do compilador

Não tenho certeza se isso vai acontecer, em parte o TypeScript tem muitos códigos de erro e eles mudam com bastante regularidade. Vale a pena voltar quando houver um site e documentos totalmente funcionando, mas por enquanto está em segundo plano.

Mostrar mais exemplos do mundo real

O novo manual até agora está fazendo um bom trabalho nisso 👍🏾 - podemos ter como objetivo mantê-lo assim. Com o restante dos documentos, tentarei mudar tudo que vejo para ser assim.

O suporte móvel no site é fraco

Estou pensando em usar o sistema de design da Microsoft (fluido) para o novo site, o que significa que o suporte móvel (com acessibilidade) deve vir “de graça”

Com algo tão complexo como o playground que é um pouco mais complicado, acho que para um celular do tamanho de um telefone, uma mentalidade de navegação / exploração é uma boa opção. Então, eu tenho uma maquete disso sendo um pouco mais próxima de uma experiência somente leitura:

Explore as melhorias da ajuda do tsc

Estou aberto a isso, mas a CLI de digitação é realmente apenas um comando, compilar (é por isso que não há necessidade de ajuda em subcomandos (embora --init meio que quebra isso))

Fornecer conselhos sobre como melhorar o DTS

Sim, estou planejando mesclar o site definitivamente digitado no site datilografado e consolidar esses documentos. Se _todos_ eles viverão no site ainda está em debate. Há um bom raciocínio para manter os detalhes reais de implementação de contribuição no repositório definitivamente digitado, enquanto as visões gerais de alto nível podem permanecer no site.

Consolidar docs / blogs / releasenotes

Uma pergunta complicada, eu não tenho uma resposta para o blog / notas de lançamento. Usamos o sistema de blog de produtos da Microsoft com todos os outros, e não tenho certeza se é uma boa ideia mover tudo isso para o próprio site. Podemos descobrir isso mais perto da hora.

No lado mais fácil, eu definitivamente gostaria de remover esse tipo de informação do wiki e deixá-lo apenas dentro do site (onde pode ser indexado pela pesquisa do site) - eu gostaria de deixar o wiki do TypeScript especificamente para contribuir com TypeScript e trabalhar com APIs do compilador TypeScript (por exemplo, quando você import * as ts from “typescript” ou constrói um plugin de servidor de linguagem)

Cubra os erros mais comuns

Isso se relaciona com o acima - há uma página de FAQ realmente extensa para esses tipos de problemas, que eu acabei de descobrir no wiki (3 anos em meu uso de TS).

Podemos tomar isso como uma linha de base e começar a puxá-los para o site principal com suas respostas também

Adicionar destaque de sintaxe

Sim, concordo, obrigado!

Em suma, acho que temos muitos deles sendo ativamente explorados ou trabalhados, e estou aberto para mais comentários à medida que continuamos trabalhando nos documentos!

Excelente trabalho, muito obrigado

Que tal emprestar / melhorar / colaborar com a experiência tsconfig do VSCode no editor Playground, em vez de criar um separado?

Torna o Playground melhor, e a experiência existente no VSCode já é decente.

Não tenho certeza do que você quer dizer. Gosta dos recursos de esquema JSON de autocompletar no VS Code? Eu estava planejando ter isso na parte do editor JSON, mas uma visão geral de todas as opções como uma GUI com rótulos é uma maneira útil de ver todas as opções e escolher.

@orta Quando o novo manual se tornar o manual oficial, os URLs que apontam para seções do manual atual serão interrompidos? Ou o novo manual estará em um URL diferente? Só estou me perguntando porque coloquei muitos links de manuais nas respostas do SO nos últimos anos (tenho certeza de que outros fizeram isso também) e seria uma pena se todos eles quebrassem. (Existe um problema ou local melhor para falar sobre os planos de migração de documentação geral?)

@orta @jcalz Estava se perguntando a mesma coisa, tenho mais de 2,5 mil respostas SO, encontrar todas as respostas com links e atualizá-los todos simplesmente não é viável. O ideal é que os links com fragmentos ainda funcionem e redirecionem para novos locais. Estou disposto a ajudar com o mapeamento, se necessário.

Sim, eu não acredito em quebrar URIs - há algumas opções para explorar.

Acho que provavelmente usará uma nova raiz de URL para o manual (por exemplo, não docs/handbook/x.html mas talvez /handbook/x.html ), e direcionará as páginas mais antigas para seu equivalente mais próximo por meio de um mapa de algum tipo.

Eu gostaria de saber o que todos os rótulos do github para este repositório significam. Alguns deles são autoexplicativos, mas outros não.

Por exemplo, "Precisa de uma proposta" não está claro para mim. Seria útil que todos os rótulos tivessem descrições mais longas, como alguns já têm.

Não é possível vincular a documentos para opções do compilador _específicas_

Minha equipe é relativamente nova no TypeScript e, como tal, nosso tsconfig.json muda com frequência e, muitas vezes, quero indicar às pessoas a documentação de opções específicas do compilador, ou seja, na forma de:

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

Links como este não funcionam, mas eu gostaria que funcionassem.

Atualmente, o único id HTML que posso ver nessa página é # compiler-options, o que não é tão útil, pois está basicamente no topo - ter um id para cada uma das opções, no entanto, seria muito útil para levar as pessoas a parte desejada da página.

Tags: compiler

@ Tyler-Murphy, corrigimos isso agora

@ssalka - sim, boa

-

Vou encerrar esta edição, reabrirei um novo no futuro com a mesma premissa, assim que avançarmos no manual e no novo site 👍

Playground datilografado:
Sinto que estou ficando louco, mas não consigo encontrar uma opção simples de 'Compartilhar' para salvar e compartilhar meu projeto (por exemplo, para adicionar a um problema do github).
Vejo todos os links em 'Exportar', mas nenhum 'Compartilhar'.

Playground datilografado:
Sinto que estou ficando louco, mas não consigo encontrar uma opção simples de 'Compartilhar' para salvar e compartilhar meu projeto (por exemplo, para adicionar a um problema do github).
Vejo todos os links em 'Exportar', mas nenhum 'Compartilhar'.

Exemplo: Link Playground

O novo site parece muito bom! No entanto, percebi que essa solicitação (links de âncora para opções do compilador) não foi feita em 😕

Parece que seria um pedido muito fácil de acomodar e seria muito útil para os recém-chegados. Espero ver isso em uma atualização futura!