Typescript: ¿Qué es lo que no le gusta del sitio web y la documentación de TypeScript?

La página "Tipos de servicios públicos" no está actualizada

Los nuevos tipos de servicios públicos a menudo se pierden o no se agregan a la página "Tipos de servicios públicos" del manual (por ejemplo, Parameters<T> ). A menudo tengo que recurrir a navegar por lib.es5.d.ts lugar del manual.

Etiquetas: docs

El patio de juegos oficial de TypeScript no es tan bueno como las alternativas de código abierto

https://typescript-play.js.org hace un mejor trabajo que el oficial: cubre múltiples versiones de TypeScript, permite compartir textos más grandes, admite todos los indicadores del compilador y el modo estricto está activado de forma predeterminada.

Etiquetas: playground

Falta de página de índice para las notas de la versión

Deseo que haya una página de índice para enumerar todas las notas de la versión anteriores en esta URL : https://www.typescriptlang.org/docs/handbook/release-notes . De esa manera, podemos realizar un seguimiento de las actualizaciones de versiones anteriores en TypeScript.

Etiquetas: docs , release notes

No hay un glosario de nombres de tipos.

Si le pasó a alguien un código como const a: "foo" | "bar" es posible que no sepa llamar a este tipo de Unión.

Esta es una barra bastante baja, pero cuando comenzamos a hablar de tipos existenciales / condicional / mapeados / etc., es bueno poder ir a una página que solo intenta definirla, pero no documentarla en profundidad para que pueda obtener una descripción general. de toda la taxonomía para este idioma

Etiquetas: types , handbook

No hay una página para compartir con gente no técnica.

Este lo necesitaba para persuadir inicialmente a las personas fuera de la ingeniería (piense en PM, gerentes no técnicos) cuál es el valor de usar TypeScript. Al final, escribí esto yo mismo, pero preferiría un funcionario.

Etiquetas: guides

La documentación Definitely Typed vive fuera de los documentos de TypeScript y está desactualizada

El proyecto TypeScript debería poseer documentos sobre esto. La documentación de Definitely Typed se encuentra en:

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

Los documentos de TS podrían contener una descripción general de qué es, por qué se usa y podemos desaprobar el sitio oficial.

Etiquetas: definitely-typed

no enseña TS progresivamente

(Editado para mayor legibilidad) Creo que los documentos son más efectivos cuando tienen una "personalidad" clara para la que están destinados. Cuando se crearon estos documentos, ES6 aún no existía. Cuando se crearon estos documentos, podría aprender todo TS en una tarde.

Los tiempos han cambiado.

Hice react-typecript-cheatsheet porque sentí que los documentos de TS específicamente no servían a las personas que ya conocían es6 y tampoco querían aprender TS avanzado de una sola vez. tan específicamente dirigido al desarrollador JS experimentado que prueba TS por primera vez. hay muchos de nosotros. Los documentos actuales son "hey, esto es lo que son las clases" o "aquí hay un montón de genéricos de aspecto aterrador en la misma página que nuestros documentos de operador de tipo".

en particular, aquí hay una lista no exhaustiva de personas a considerar que podrían servir como un maestro progresivo:

• personas que solo quieren usar TS con JSDoc, sin paso de compilación
• personas que desean usar TS sin escribir ningún genérico tanto como sea posible
• personas que están migrando bases de código de JS / Flow a TS
• personas que son nuevas en TS, adoptaron TS, pero ven errores poco familiares y detallados por primera vez y no tienen idea de cómo lidiar con ellos (esta es la audiencia de " solución de problemas ") u optar por no participar
• personas que desean publicar bibliotecas de TS frente a aplicaciones de TS
• personas que quieren aprender a usar operadores de tipo
• personas que quieran aprender sobre las utilidades de tipos que pueden ayudarles
• personas que necesitan escribir bibliotecas sin tipo (es en gran medida un efecto de red y un interés de TS hacer que la escritura de .d.ts sea tan ridículamente fácil y bien documentada como sea posible)
• y aaaaaa todo el camino al final, las personas que quieren aprender a escribir su propia lógica de tipo genérico
• (tal vez) personas que quieren escribir complementos que necesitan atravesar TS AST

Todas estas son etapas en el viaje de adopción de TS, debemos trazarlo y asegurarnos de que no haya un acantilado en los documentos donde las personas se caigan porque no saben qué hacer y, por lo tanto, asumen que es demasiado difícil.

Creo que los documentos pueden hacer mucho para ayudar a disipar el mito de que:

• necesita la máxima seguridad de tipos en todo momento (no solo en tsconfig, sino también en las elecciones que hacemos al escribir las funciones)
• TS es para programadores OO (sí, he visto esto)
• TS es solo para desarrolladores de C # / Java que vienen a JS y pierden tipos, no tiene un valor real para los desarrolladores de JS
• debería poder averiguar cómo resolver los errores de TS por su cuenta
• en general, TS tiene una curva de aprendizaje alta para empezar

Si hay recursos disponibles, podemos y debemos apuntar a grandes comunidades de desarrolladores específicas para ayudar a su adopción, por ejemplo, para React, pero también para Vue y también para Node, etc. Puede hacer esto fuera de los documentos principales, por ejemplo, los documentos de Vue hacen una distinción entre el libro de cocina y la guía, centrándose en ejemplos prácticos en contexto.

esto es probablemente un obstáculo tan grande para la adopción de TS en la etapa tardía (es decir, personas que requieren más documentos / herramientas / garantía / agarre para poder venderse en TS) como puedo imaginar.

etiquetas: docs

La especificación del lenguaje TypeScript enlazado está completamente desactualizada

Directamente en la página principal está enlazando a la "Especificación del lenguaje TypeScript".

Lea la especificación en GitHub o descárguela como docx o pdf.

Sin embargo, esa especificación está completamente desactualizada (bloqueada en la versión 1.8, última actualización real en enero de 2016) y no se mantiene. Sería mejor dejar de mencionar la especificación.

Etiquetas: spec specification outdated

Widget similar a un patio de recreo para muestras de código

Presente todas las muestras de código en documentos en un widget similar a un patio de recreo, con todas las sugerencias útiles, aspectos destacados, etc.

Idealmente, con la capacidad de aparecer en un patio de recreo completo, con edición y observación de JS / mecanografía emitidos.

Esto, naturalmente, dependería de Official TypeScript Playground no es tan bueno como la sugerencia de

Documentación de la API que solo existe en las notas de la versión

Algunos tipos, por ejemplo, unknown , solo se documentan en las notas de la versión , lo que los hace difíciles de descubrir.

Etiquetas: docs

Zona de juegos de Fourslash

Hay una gran cantidad de archivos en / tests / cases / compiler que, junto con las líneas de base, se comportan como materia oscura críptica. Estos megabytes se pueden reutilizar como documentos / demostraciones.

• hacer que TS playground cargue cualquier archivo del repositorio de TS a través de algo como: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• hacer que el patio de juegos de TS entienda 'fourslash'
• agregar comentarios descriptivos a esos archivos

Eso permitiría a alguien vincular URL a casos de sintaxis interesantes y ayudaría a la gente a jugar y enviar otras pruebas extravagantes.

Zona de juegos que EXPLICA una sintaxis de TS dada

No es difícil tropezar con una sintaxis TS complicada que es realmente difícil de comprender. Genéricos recursivos, combinados a través de uniones y tipos indexados funky ... Un gran nido de ciempiés tan aterradores son los mecanografiados, por ejemplo.

¿Qué pasaría si uno pudiera pegar un trozo de sintaxis rica en ángulos y observar una vista detallada y digerible por humanos o un diagrama? Ya sabes, donde indudablemente puedes ver claramente que A es una clase, y B es un tipo de unión, y C es un parámetro genérico para D etcétera.

Comenzando como una ingenua 'letra bonita AST detallada', con el tiempo y la contribución de la comunidad, esto puede expandirse tanto en un reconocimiento de patrones más profundo como en imágenes interactivas más ricas y diagramas similares a UML.

no hay búsqueda de la documentación

A menudo tengo que recurrir a buscar en Google cómo hacer algo con mecanografiado en lugar de tener el documento principal como fuente de verdad, por ejemplo, con DocSearch como en los documentos de React.

Etiquetas: search , exploration

Destacar proyectos comunitarios

Pueden ser cosas como reuniones, charlas comunitarias o libros.

Pero también podrían ser proyectos de software más grandes que utilicen TypeScript de los que alguien pueda aprender.

Etiquetas: Community

Proporcionar guías para activar indicadores de compiladores específicos.

Por ejemplo, si activara noImplicitReturns ¿qué tipo de problemas abordaría y cómo debo manejarlos? Enviamos este tipo de recomendaciones con las notas de lanzamiento de la versión para el momento en que se introdujeron esas banderas, por lo que buscarlas es complicado.

Etiquetas: tsconfig

Crear una página de índice de errores del compilador

El lenguaje rust hace esto , es un gran esfuerzo comenzar (TS tiene más de mil errores hoy en día) pero el mensaje de error en tsc es conciso, tenerlos en un sitio los hace indexables por motores de búsqueda, mejorables y con código de ejemplo .

Etiquetas: compiler

¿Qué pasaría si uno pudiera pegar un trozo de sintaxis rica en ángulos y observar una vista detallada y digerible por humanos o un diagrama?

Creo que esto sería genial, pero en algunos casos creo que una explicación altamente estructurada de cómo se descompone un tipo (que parece algo posible de generar automáticamente) no es tan útil como reconocer algunas combinaciones comunes de tipos y patrones que logran un objetivo particular. Como ejemplo, digamos que quiero que alguien me explique qué es esto:

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

Yo _podría_ decirte que

X es un alias de tipo con un parámetro de tipo T que está restringido a object . Cuando se crea una instancia con T , produce un tipo mapeado, donde para cada constituyente K del tipo keyof T , el valor es el tipo de acceso indexado T[K] . X luego produce un tipo de acceso indexado en ese tipo mapeado con el tipo keyof T .

pero sería mucho más útil y, sin embargo, extraordinariamente difícil de producir por cualquier persona que no sea un humano con conocimientos prácticos de TypeScript, decirle:

X obtiene la unión de los tipos de valores de miembro de T .

Creo que quizás tener una colección de "recetas" de patrones como este podría ser útil.

La página de tipos avanzados es solo una especie de vertedero para cualquier tipo no obvio (he robado un montón de ideas de TypeScript para una herramienta de análisis estático de PHP , así que me encuentro mucho en esa página).

Un montón de ideas están interconectadas, pero eso podría hacerse con hipervínculos entre páginas.

La sección Type Guard / Type Predicate se siente especialmente como si mereciera su propia página.

Orientación para escribir bibliotecas de textos mecanografiados

Descubrí que enviar una biblioteca escrita en TypeScript no es muy fácil. Muchos casos extremos a considerar en función de su consumidor objetivo. Tengo mis propias opiniones sobre esto que son totalmente debatidas, pero documentar la guía oficial para los autores de bibliotecas sería increíble.

Etiquetas: libraries , guidance

La navegación móvil puede ser difícil

No puedo leer el manual del sitio web desde el móvil, lo cual es bastante decepcionante. También sería genial si pudiera tener la navegación anterior / siguiente en la parte inferior de la página en cada página del manual.

de un tweet

Etiquetas: nav

Utilice más ejemplos del mundo real

Algunos de los ejemplos actuales son demasiado genéricos o abstractos, y utilizan convenciones de nomenclatura basadas en letras (A, B, C) o términos que no se pueden relacionar (foo, bar, baz, args, obj, etc.). Espero ver más ejemplos del mundo real (formas, animales, productos, usuarios) y casos de uso legítimos (llamadas a API, registro, manejo de errores, formateo de datos). Esto sería especialmente útil para conceptos que ya son abstracciones, como Genéricos y Tipos avanzados.

Nota: Algunas áreas de la documentación ya manejan este problema, pero es impredecible.

Etiquetas: examples

Biblioteca de ejemplo y mejores prácticas

Muestre cómo escribir diferentes tipos de funciones. Like lodash tiene todo tipo de funciones sofisticadas como seleccionar, extender, aplanar, etc. Describe cómo escribirlas.

Una biblioteca que aumenta gradualmente la complejidad. Incluso podría haber leído más enlaces a confirmaciones que muestran cómo se usa una determinada cosa en TS en producción.

Sea lo que sea lo que termine siendo construido, espero que sea muy fácil para que alguien agregue ejemplos. Supongo que será un manual de TS como git repo.

Los mejores proyectos de código abierto suelen tener la mejor documentación y una nueva experiencia de usuario.

Hagamos que TS sea aún más acogedor para los nuevos usuarios.

Mejor descripción de las opciones de tsconfig

Descripción actual en la página Opciones del compilador

• Proporciona una descripción muy vaga de cada opción y cómo afecta la compilación y la verificación de tipos. Algunos ejemplos pueden resultar realmente útiles.
• El formato de la tabla deja un pequeño espacio de descripción.
• No hay información sobre la versión de TypeScript
• El orden alfabético no es útil, algunas opciones están estrechamente relacionadas entre sí como target , module y lib o todas las opciones similares estrictas. Es difícil comprenderlos bien cuando los mira por separado. No comprenderá la opción lib sin comprender primero target .
• La mayoría de las veces la gente usa esas opciones en archivos tsconfg, no como opciones tsc , por lo que el formato actual podría resultar confuso para los recién llegados.
• Las descripciones más detalladas de algunas opciones se encuentran dispersas en la documentación, por ejemplo, las opciones @types , typeRoots y types se describen en la página tsconfig.json y baseUrl y paths en Resolución de módulo

Está conectado con Proporcionar guías para activar la sugerencia de

editar:
Sin mencionar las nuevas opciones como la relacionada con la creación de proyectos compuestos, para los cuales no hay información en los documentos y se ve obligado a reunir la imagen completa en función de las notas de la versión y los problemas de GitHub.

Etiquetas: tsconfig

Recopile documentación, blogs y otros recursos oficiales en un solo lugar

Si pudiéramos recopilar todos los recursos oficiales sobre TypeScript en un solo lugar (por ejemplo, www.typescriptlang.org ), ¡sería increíble! 😊

Por ejemplo, la publicación del blog sobre el anuncio de la versión 3.5 está en otro lugar ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

Y, la nota de la versión v3.4 está en otro lugar:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Siento que esto no es muy útil y confuso para los desarrolladores de TypeScript. 😕

Etiquetas: blog , resources

cree tsconfig.json completando el formulario de interfaz de usuario con sus preferencias y la configuración del proyecto

Sería bueno que la documentación contuviera un formulario / asistente que ayude a generar tsconfig.json que se adapte al entorno de destino (navegador, nodeJS), las preferencias del usuario (tan estrictas o indulgentes como desee el usuario) y la estructura del directorio del proyecto. Actualmente, las Opciones del compilador de TS contienen varias opciones obsoletas y algunos indicadores del compilador, que a primera vista parece que podrían hacer más o menos lo mismo (cuáles son las diferencias entre algunas opciones, por ejemplo, las relacionadas con rutas / directorios / raíces). El tsconfig generado debe cumplir con las mejores prácticas del equipo central de Microsoft TypeScript. Otra pregunta de orientación podría incluir:

• ¿Cuál es la experiencia del equipo de desarrollo del proyecto con TypeScript?
• es el proyecto de una biblioteca o aplicación (en el caso de la biblioteca con pocas dependencias puede ser más fácil de usar algunas de las características estrictas, tales como strictNullChecks , por lo que se podría sugerir dependiendo de la experiencia del usuario)
• es la aplicación que usa JSX / TSX (React)
• ¿Estás usando un marco / biblioteca, que usa decoradores?
  
  
  
  • en caso de que se emitan los metadatos de los decoradores, por lo que podría ser utilizado por el marco / biblioteca en tiempo de ejecución (mencione los marcos y bibliotecas, como Angular, Aurelia como ejemplo)
  
  

Etiquetas: tsconfig , examples , guides , wizard , exploration

@orta Creo que sería genial hacer una versión móvil del parque infantil, o al menos adaptar la actual. A partir de ahora, el patio de recreo se ve horrible en el móvil (la captura de pantalla está hecha en iPhone 7).

Ojalá hubiera una sección en el área del "manual" del sitio web que hablara específicamente sobre los objetos literales y las diversas formas en que puede escribirlos.

Por ejemplo, constantemente tengo que buscar en Google algo como "literal de objeto mecanografiado con cualquier propiedad" o "literal de objeto mecanografiado con una propiedad requerida y cualquier otra propiedad".

Y siempre tengo que buscar el tipo { [key: string]: any } , que en realidad no se discute en ninguna parte.

Algunas de estas cosas se hablan en las "Interfaces", pero eso no es obvio de inmediato.

Aumento de tipos de proveedores

A veces, cuando trabajo con tipos DefinitelyTyped u otras definiciones de módulos de proveedores, encuentro que necesito ajustar las definiciones a:

1) Sobrescribir / modificar la definición existente
2) Agregar nuevos métodos / propiedades

No he podido encontrar documentación sobre la forma correcta de realizar la tarea en diferentes escenarios. Tampoco he tomado buenas notas cuando necesitaba hacerlo yo mismo 🐙. https://www.typescriptlang.org/docs/handbook/declaration-merging.html aborda el problema del código de origen, pero no he hecho que ese consejo funcione para tipos / exportaciones de módulos de terceros.

Obviamente, es genial abrir PR de inmediato para corregir / actualizar los tipos en el repositorio correspondiente, pero puede llevar un tiempo fusionarse nuevamente en la rama maestra, lo que puede interrumpir el flujo de trabajo y forzar la adición de conversiones temporales de any y una seguimiento TODO.

Etiquetas: vendor

Documentación de la API del compilador

La wiki tiene información sobre el uso de la API del compilador (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) pero solo muestra ejemplos de cómo usarla para lograr ciertos objetivos. Sería genial tener más información de estilo JSDoc para enumerar los objetos y métodos específicos que existen y aprender sobre lo que hacen. En este momento estoy tratando de aprender la API y necesito mirar el código fuente mecanografiado para averiguar qué está pasando.

(ignore si esto no se ha hecho solo porque la API aún no es estable como se menciona en la wiki)

Etiquetas: compiler

Tutoriales que se centran en TS en comparación con los idiomas existentes

Mucha gente viene a TypeScript como su segundo (o más) idioma. Una forma de simplificar el aprendizaje de TypeScript es compararlo con un lenguaje existente que ya conoce. Podríamos elegir los principales lenguajes de programación por popularidad, por ejemplo, JS, Java, C #, PHP, C (+ CPP) y Ruby; luego, hemos dirigido tutoriales que asumen que tiene el conocimiento de cómo funciona ese lenguaje.

En este momento solo asumimos que conoce JS.

Etiquetas: tutorials

Asegúrese de que sea accesible de forma predeterminada

Asegúrese de que linters como accessibilityinsights.io pasen

Etiquetas: infra

URL cortas que se pueden compartir para el área de juegos

Sería genial si el botón "Compartir" del patio de recreo de TypeScript produjera URL cortas, en lugar de volcar todo el código fuente en la URL.

Alternativamente, permita que la URL contenga una ID de gist de github que complete el área de juegos. por ejemplo: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Etiquetas: playground

Ejemplos con diferentes configuraciones (para diferentes casos de uso / escenario)

Me resultó complicado saber cómo podría configurar mi base de código de TS y qué ejemplos podría seguir para varias bases de código, por lo que sería genial si una lista de ejemplos como https://github.com/microsoft/TypeScriptSamples/ apareciera en el sitio web para mostrar cómo se configuraría el tsconfig.json y cómo debería estructurar los archivos TS para que funcionen según lo previsto.

Etiquetas: docs , examples

No hay ninguna razón obvia por la que los documentos estén en el wiki o en el manual.

La página en this en el wiki es_amplia_ y desearía haberla encontrado antes. Deberíamos averiguar qué tipo de cosas deberían vivir en la wiki (especialmente porque nadie más puede editarlo fácilmente (la gente externa tiene que enviar un PR)) y mover las otras cosas al sitio.

Mejora la navegación entre temas y títulos.

Temas enormes como el Manual § Tipos avanzados tienen una navegación deficiente entre títulos separados, ni tampoco un botón para

Aquí hay un buen ejemplo de navegación en este libro de git de Assembly Script: https://docs.assemblyscript.org/basics/environment

Etiquetas: website , handbook , navigation

Edición de código de área de juegos amigable para dispositivos móviles

Según tengo entendido, la edición de código compatible con dispositivos móviles con resaltado de sintaxis y todas las demás funciones del IDE es una molestia.

Sin embargo, me he encontrado queriendo jugar con fragmentos de código mientras estoy en mi teléfono, lejos de una computadora de escritorio / portátil, con bastante frecuencia.

No me importaría un campo simple <textarea> , en lugar de un editor resaltado de sintaxis para uso móvil.

Es posible que los errores se encuentren en otra página o en una ventana emergente o en algún otro elemento html.

Etiquetas: zona de juegos, móvil, editor de código

Documento que agrega la extensión .js para módulos es6 compatibles con el navegador

¡No se menciona en ninguna parte que TypeScript se puede usar perfectamente para generar módulos es6 que funcionan en el navegador simplemente agregando la extensión .js al nombre de la importación! El único lugar donde parece existir esta información es en este hilo:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

No estoy seguro de qué versión de TS lo agregó, pero las importaciones como './file.js' ahora funcionan (incluso si el archivo es realmente file.ts).

Para mí, esta fue una característica enorme ... ¡¿pero oficialmente no existe ?!

La página de tipos avanzados no incluye el tipo Omit<T, K> .

Omit<T, K> se agregó recientemente en TypeScript 3.5 , pero la página de tipos avanzados aún tiene la siguiente exención de responsabilidad:

Nota: El tipo Excluir es una implementación adecuada del tipo Diff sugerido aquí. Hemos utilizado el nombre Excluir para evitar romper el código existente que define un Diff, además creemos que el nombre transmite mejor la semántica del tipo. No incluimos el Omitirtype porque está trivialmente escrito como Pick>.

Proporcionar documentación de configuración del proyecto para Linters

Como parte de la configuración de un proyecto, incluya cómo configurar con un Linter, lo más probable es que solo mecanografíe-eslint, que se supone que el proyecto debe usar por sí mismo.

Etiquetas: linter

No hay nada que cubra los errores más comunes o las limitaciones de TypeScript.

Cuando aprendes TypeScript por primera vez, hay ciertos patrones que no + nunca serán compatibles con TypeScript. Uno de los más simples:

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

Comencé a presentar TypeScript a mi empresa, y casos como este aparecen mucho, así que comencé a documentarlos en una guía de estilo de preguntas frecuentes / solución de problemas. Está creciendo rápidamente (tenga en cuenta que está en un estado difícil):

Construyendo un objeto de una propiedad a la vez
Por qué no recibe errores cuando los desea: exceso de control de propiedad
Cómo acceder a propiedades opcionales, incluidas las de uniones
Por qué Object.keys y Object.entries no hacen lo que quieres
Hacer filtro de filtro, hacer reducir el trabajo sin errores.
Tipo de refinamiento perdido

Si parte de esta información está en los documentos, no he podido encontrarla. Solo los he entendido a través de años de prueba / error y leyendo los problemas más vinculados en Github.

Etiquetas: errors , troubleshooting , limitations

Proporcionar documentación clara sobre cómo agregar definiciones de tipos personalizadas

Hay varias bibliotecas que no incluyen tipos y que no tienen un paquete @types/* disponible. Me gustaría poder escribir mis propios archivos de declaración para estos dentro de mi proyecto, pero no parece haber ninguna documentación sobre la forma 'correcta' de escribirlos y obtener mecanografiado para reconocerlos. Digamos que estoy importando un módulo de npm. ¿Necesito usar declare module x ? o declare module "x" ? o usa un espacio de nombres? o simplemente exportar los tipos? ¿Hay un lugar específico donde deba colocar estos archivos? ¿Qué opciones de configuración necesito establecer? typeRoots ? types ? paths ? include ? ¿o que? - Todo lo que he encontrado hasta ahora son mensajes de error confusos, opciones de configuración mal explicadas y preguntas SO obsoletas.

Etiquetas: docs

Falta de documentación fuera de línea

Las herramientas de desarrollo básicas modernas como git o npm tienen su propio subconjunto de comandos que nos permiten acceder a documentación / referencia sin conexión, por ejemplo:

$ git help ls-remote
$ npm help search 

Creo que sería bueno tener esa característica (aunque el TS es un poco diferente).
Nos permitiría explorar documentos localmente a través del comando help like sin necesidad de consultar el sitio / 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

Etiquetas: offline , search , cli , local

¡Los ejemplos necesitan colores que los distingan mejor!

Como debería ser:

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

Cómo es actualmente:

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

Hay un poco de azul, pero eso es todo.

Hola amigos, he estado pendiente de este problema mientras pensaba en la estructura general del sitio y la documentación general durante el último mes. Ahora que este problema se ha resuelto y tengo un poco más de comprensión sobre cómo me gustaría que se vieran los documentos.

Intentemos analizar todos estos puntos en función de las reacciones, mezclando un poco los pies para mejorar la legibilidad.

Los documentos de la API a veces solo pueden existir en las notas de la versión

Este será complicado, en parte porque en este momento no estoy seguro de qué solo vive en las notas de la versión.

Con respecto al lenguaje y la sintaxis, espero que esto se solucione y mejore con el nuevo manual que se publicará próximamente, que está revisando todo el lenguaje. Para el resto de la documentación, creo que parte del nuevo mapa del sitio debería cubrir la mayoría de los casos, pero sigue siendo un WIP.

Sin búsqueda en el sitio web

Sí, estoy de acuerdo, este es definitivamente crítico para el nuevo sitio.

El sitio web es de código cerrado

¡Reparado! https://github.com/microsoft/TypeScript-website

El nuevo trabajo saldrá de la rama maestra, pero por ahora se puede acceder al sitio anterior arriba y tomar RP. También he estado moviendo problemas del repositorio de TypeScript aquí, por lo que es más fácil hacer un seguimiento de todos ellos.

Páginas de utilidades no actualizadas

¡Reparado! En parte, fusioné muchas relaciones públicas y obtuve el manual actual de la comunidad. Además de asegurarse de que aparezca en la navegación (en lugar de solo desde una búsqueda web)

Descripciones mejoradas de las opciones de TS Config

Comencé a explorar esto durante el fin de semana (cómo podemos asegurarnos de que el compilador y el sitio web compartan la misma fuente de datos inicial para estos documentos, y qué puede construir el sitio web además de eso para proporcionar más contexto)

Algunos ejemplos de dirección hasta ahora:

• mis propias notas de 2017
• He estado charlando con Ethan Arrowood @matterhorndev, cuyo tsconfig-ui podría ser la base para crear un explorador de TSConfig

El área de juegos no es tan buena como las alternativas

¡Reparado! Considero que esto es un trampolín positivo en la dirección general que me gustaría que fuera el patio de recreo. Tengo algunas maquetas de ejemplo que brindan una perspectiva a más largo plazo sobre cómo debería verse y sentirse el patio de juegos para que sea realmente lo mejor de su clase.

( haga clic para exploraciones de figma )

URL breves que se pueden compartir para el área de juegos

Fijo, ver más abajo

Sin glosario de nombres de tipos

Comencé a escribir la mía propia , a medida que aprendí el compilador; esperaría ver esta fuente en el nuevo manual. También afecta a los ejemplos del patio de recreo, que sirve como un glosario de ejemplos para algunos de los tipos más avanzados.

[zona de juegos ex1, zona de juegos ex2]

No enseña TS de forma progresiva

Esto está destinado a ser abordado en el nuevo manual, para citar algunos de # 29288 (desplácese hasta New handbook )

Escribir un documento general para todos los usuarios es difícil porque la audiencia de TypeScript es amplia y una de las fortalezas (y debilidades) del manual actual es que intenta servir a todos a la vez. Tenemos varios grupos diferentes de desarrolladores que tienen diferentes expectativas al aprender TypeScript, y necesitamos ajustar el nivel de exposición de diferentes conceptos. Dado eso, nuestro objetivo es organizar el manual en tres partes diferentes:

1. Introducciones personalizadas (configuración para el manual básico)
   
   
   
   1. El manual básico (todos leen esto)
   
   
   2. Páginas de referencia (algo así como apéndices / inmersiones profundas)
   
   

Efectivamente, tiene algunos puntos de partida diferentes y luego intenta enseñar el idioma una vez que se familiariza con el ecosistema circundante.

¿Eso aborda todo en el comentario? No, solo el comienzo. El mapa del sitio actual que tengo es bastante extenso, y estos son los tipos de problemas que me interesan

Dejé un margen de maniobra en mis libros de cocina y guías de mapas del sitio actuales, y los libros de cocina son algo con lo que podemos fomentar un mayor apoyo de la comunidad.

Proporcionar guías

Me tomé el tiempo para comenzar a clasificar y actualizar los ejemplos de código actuales que se encuentran actualmente en el sitio web de TypeScript. Todavía estoy averiguando qué muestras es mejor dejar de nuestro lado en lugar de redirigir a la documentación oficial (por ejemplo, si un proyecto ahora es compatible de forma nativa con TypeScript y tienen sus propios documentos)

Al igual que antes, creo que la sección de libros de cocina y guías reales del sitio debería ser suficiente para cubrir esto.

La especificación de idioma no está actualizada

Sí, no sé si puedo eliminarlo directamente del repositorio principal, pero no se mencionará en el nuevo sitio.

Proporcione mejores experiencias similares a IDE para ejemplos de código

Esto está actualmente en el nuevo sitio del manual , aunque también tendremos que trasladarlo al nuevo sitio. También proporciona mensajes de error resaltados y en línea, lo que me entusiasma.

Página de índice de errores del compilador

No estoy seguro de si esto sucederá, en parte, TypeScript tiene muchos códigos de error y cambian con bastante regularidad. Vale la pena volver una vez que haya un sitio y documentos en pleno funcionamiento, pero por ahora está en un segundo plano.

Mostrar más ejemplos del mundo real

El nuevo manual hasta ahora está haciendo un buen trabajo en esto 👍🏾 - podemos apuntar a que siga siendo así. Con el resto de los documentos, intentaré cambiar todo lo que vea que sea así.

El soporte móvil en el sitio es débil

Estoy pensando en usar el sistema de diseño de Microsoft (fluido) para el nuevo sitio, lo que debería significar que el soporte móvil (con accesibilidad) debería ser "mayormente gratuito".

Con algo tan complejo como el patio de recreo que es un poco más complicado, creo que para un teléfono móvil del tamaño de un teléfono, una mentalidad de navegación / exploración es una buena opción. Entonces, tengo una maqueta de eso que está un poco más cerca de una experiencia de solo lectura:

Explore las mejoras de ayuda de tsc

Estoy abierto a esto, pero la CLI mecanografiada es en realidad solo un comando, compilar (por eso no hay necesidad de ayuda con los subcomandos (aunque, en cierto modo lo rompe))

Brindar consejos sobre cómo mejorar DTS

Sí, planeo fusionar el sitio web definitivamente mecanografiado en el sitio web mecanografiado y consolidar esos documentos. Si _todos_ ellos vivirán en el sitio todavía está en debate. Hay un buen razonamiento para mantener los detalles de implementación reales de la contribución en el repositorio definitivamente escrito, mientras que las descripciones generales de alto nivel pueden vivir en el sitio.

Consolide documentos / blogs / notas de publicación

Uno complicado, no tengo una respuesta para el blog / notas de lanzamiento. Usamos el sistema de blogs de productos de Microsoft con todos los demás, y no estoy seguro de si es una buena idea mover todo eso al sitio web. Podemos imaginarlo más cerca de la hora.

En el lado más fácil, definitivamente me gustaría eliminar este tipo de información de la wiki y dejarla solo dentro del sitio web (donde puede ser indexada por la búsqueda del sitio); me gustaría dejar la wiki de TypeScript específicamente para contribuir a TypeScript y trabajar con las API del compilador de TypeScript (por ejemplo, cuando import * as ts from “typescript” o crea un complemento de servidor de idiomas)

Cubra los errores más frecuentes

Esto se relaciona con lo anterior: hay una página de preguntas frecuentes muy extensa para este tipo de problemas, que acabo de descubrir en la wiki (3 años después de mi uso de TS).

Podemos tomar esto como una línea de base y comenzar a incluirlos en el sitio web principal con sus respuestas también.

Agregar resaltado de sintaxis

¡Sí, de acuerdo, gracias!

Considerándolo todo, creo que tenemos muchos de estos en estudio o en los que estamos trabajando activamente, y estoy abierto a recibir más comentarios a medida que seguimos trabajando en los documentos.

Impresionante trabajo muchas gracias @orta !

¿Qué tal pedir prestado / mejorar / colaborar con la experiencia tsconfig de VSCode en el editor de Playground, en lugar de crear uno separado?

Hace que Playground sea mejor y la experiencia existente en VSCode ya es medio decente.

No estoy muy seguro de a qué te refieres. ¿Te gustan las funciones de esquema JSON de autocompletar en VS Code? Estaba planeando tener eso en la parte del editor JSON, pero una descripción general de cada opción como una GUI con etiquetas es una forma útil de ver todas las opciones y elegir.

@orta Cuando el nuevo manual se convierta en el manual oficial, ¿se

@orta @jcalz Me preguntaba lo mismo, tengo más de 2.5K SO respuestas, encontrar todas las respuestas con enlaces y actualizarlas no es factible. Idealmente, los enlaces con fragmentos seguirían funcionando y se redirigirían a nuevas ubicaciones. Estoy dispuesto a ayudar con el mapeo si es necesario.

Sí, no creo en romper URI , hay algunas opciones para explorar.

Creo que probablemente va a utilizar una nueva raíz de URL para el manual (por ejemplo, no docs/handbook/x.html pero tal vez /handbook/x.html ), y hacer que las páginas más antiguas se redirijan a su equivalente más cercano a través de un mapa de algún tipo.

Me gustaría saber qué significan todas las etiquetas de github para este repositorio. Algunos de ellos se explican por sí mismos, pero otros no.

Por ejemplo, "Necesita propuesta" no me queda claro. Sería útil que todas las etiquetas tuvieran descripciones más largas, como algunas ya lo hacen.

No se puede vincular a los documentos para las opciones del compilador _specific_

Mi equipo es relativamente nuevo en TypeScript y, como tal, nuestro tsconfig.json cambia con frecuencia y, a menudo, quiero señalar a la gente la documentación para opciones específicas del compilador, es decir, en la 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

Enlaces como este no funcionan, pero me gustaría que lo hicieran.

Actualmente, la única identificación HTML que puedo ver en esa página es # compiler-options, que no es tan útil ya que está básicamente en la parte superior; sin embargo, tener una identificación para cada una de las opciones sería muy útil para que la gente la parte deseada de la página.

Etiquetas: compiler

@ Tyler-Murphy lo hemos arreglado ahora

@ssalka - sí, buena

-

Voy a cerrar este problema, volveré a abrir uno nuevo en el futuro con la misma premisa una vez que hayamos avanzado más en el manual y el nuevo sitio 👍

Patio de juegos con mecanografiado:
Siento que me estoy volviendo loco, pero no puedo encontrar una opción simple 'Compartir' para guardar y compartir mi proyecto (por ejemplo, para agregar a un problema de github).
Veo todos los enlaces en 'Exportar' pero no en 'Compartir'.

Patio de juegos con mecanografiado:
Siento que me estoy volviendo loco, pero no puedo encontrar una opción simple 'Compartir' para guardar y compartir mi proyecto (por ejemplo, para agregar a un problema de github).
Veo todos los enlaces en 'Exportar' pero no en 'Compartir'.

Ejemplo: Enlace de patio de recreo

¡El nuevo sitio se ve muy bien! Sin embargo, noté que esta solicitud (enlaces de anclaje para las opciones del compilador) no llegó en 😕

Parece que sería una solicitud muy fácil de acomodar y sería muy útil para los recién llegados. ¡Espero verlo en una futura actualización!