Documentación Siempre Precisa

A lo largo de los años, como diseñador e ingeniero, he escrito documentación para muchos proyectos diferentes, a veces con prisa y otras veces con un equipo durante muchos meses. Una constante en cada superficie es que no pasa mucho tiempo antes de que tú o tus compañeros de equipo comiencen a encontrar explicaciones desactualizadas y ejemplos de código. Soy Travis Arnold, y a lo largo de mi carrera, he visto cómo la documentación desactualizada puede causar fricción en los flujos de trabajo y erosionar la confianza en los proyectos. Es un desafío que enfrentan los equipos de ingeniería de todos los tamaños, y en esta charla explicaré por qué la documentación se desvía, cómo detectarlo temprano y cómo los componentes de servidor de React pueden ayudar a mantener tu documentación precisa a medida que el código cambia.

Cubriremos tres temas principales. Por qué la documentación se desvía, usar componentes de servidor de React para mantener la documentación sincronizada, y finalmente cómo escribir documentación precisa en todas partes. Comencemos con algo que todos conocemos muy bien. Un ejemplo de código. Todos hemos copiado fragmentos de código que se proporcionan como una fuente de verdad solo para encontrar errores de TypeScript más tarde al pegarlos en nuestra base de código. Imagina que un desarrollador está emocionado por implementar una característica, pero se detiene por errores inesperados en la documentación desactualizada. Esto es desviación de la documentación, y desperdicia horas de tiempo.

Está sucediendo por algunas razones. La primera es que, si bien los generadores de documentación tradicionales funcionan bien para documentos simples, tienen varias limitaciones. Producen un sitio HTML completamente horneado que es difícil de personalizar. Exponen JSON que requiere trabajo de integración adicional. A menudo requieren su propio proceso de construcción. Y no pueden actualizar granularmente los tipos generados lo que crea cuellos de botella de rendimiento. Y si deseas personalizar o sobrescribir la salida o conectarla a tu sistema de diseño, terminas creando soluciones alternativas y orquestando múltiples herramientas que deben mantenerse sincronizadas. Una de las razones más comunes por las que la documentación se desvía es la falta de una fuente única y autorizada de lo que realmente es cierto. En cambio, la información está dispersa por todas partes. El código fuente vive en un repositorio, las especificaciones de la API están en un sitio de documentación separado, y los ejemplos de uso se pegan en materiales de marketing. Cada una de estas fuentes evoluciona de manera independiente y a menudo fuera de sincronía.

Esta fragmentación significa que no hay garantía de cuál artefacto es la referencia real. A medida que los equipos actualizan el código, la documentación y las especificaciones en paralelo, inevitablemente aparecerán contradicciones. Para resolver esto, la documentación necesita estar estrechamente vinculada al propio código fuente. Cuando los documentos se generan y validan contra la base de código real, eliminas cualquier ambigüedad. Los documentos se desvían no solo porque no están conectados a una única fuente de verdad, sino también porque están dispersos en una gran cantidad de lugares.

Los documentos existen en read me's, sitios, blogs, diapositivas y materiales de marketing. Hay diferentes equipos manteniendo esos servicios, lo que puede causar desviación. Y copiar y pegar propaga y los cambios de último minuto a menudo se pasan por alto. Un fragmento de código puede comenzar en el IDE de un desarrollador, copiarse en el read me, y luego aparecer como una captura de pantalla en marketing. Cuando el código cambia, estas copias a menudo permanecen desactualizadas. Es similar a un juego de teléfono donde la verdad puede descomponerse fácilmente.

Los documentos se volverán obsoletos si no están vinculados a una fuente de verdad. Por ejemplo, en una startup en la que trabajé, no teníamos un equipo de documentación dedicado, y los ingenieros y diseñadores ayudaban cuando podían. Pero debido a esto, nuestras herramientas de documentación tenían que encajar directamente en nuestro flujo de trabajo normal o simplemente no se usarían. Construir estos sistemas por ti mismo rara vez es práctico. Necesitas un conocimiento profundo de los árboles de sintaxis abstracta, también conocidos como ASTs, que representan la estructura de tu código, además de herramientas para recorrerlos y transformarlos. Para lenguajes como TypeScript, también necesitas entender la API del compilador de TypeScript y el verificador de tipos.

Con la introducción de los componentes de servidor de React, ganamos una habilidad crucial para renderizar componentes en el servidor. Esto se combina extremadamente bien con herramientas como TypeScript. Al generar documentación directamente desde los componentes usando el compilador de TypeScript, evitas copiar fragmentos de código desactualizados. En su lugar, muestras información directamente desde tu base de código para que tus ejemplos y documentos se mantengan sincronizados con cada cambio.

Veamos cómo el uso de componentes de servidor de React puede ayudarnos a integrar el compilador de TypeScript en el proceso. Los componentes de servidor de React resuelven varios problemas clave que los hacen una excelente opción para la documentación. Primero, tenemos la ejecución del lado del servidor, lo que, dado que ahora podemos ejecutar componentes en el servidor, podemos acceder de manera segura a los archivos del proyecto TypeScript y otros metadatos como el historial de git. También podemos trasladar el trabajo pesado al servidor, lo que significa que ahora podemos analizar y tipar tipos y formatear código en el servidor en lugar de en el navegador. Esto significa que los usuarios no tienen que descargar ningún código adicional.

También tenemos composición ahora. Así que, ahora tenemos una renderización flexible de los mismos componentes, que se pueden usar en readmes, sitios de documentación y marketing. A continuación, tenemos la transmisión, que es enorme. Los componentes de servidor de React están construidos alrededor de la transmisión, y podemos orquestar una gran experiencia de documentación no solo en producción sino también localmente.

Finalmente, tenemos la evaluación perezosa. El mejor rendimiento es no hacer nada en absoluto. Los componentes de servidor de React nos permiten aplazar el trabajo hasta que sea absolutamente necesario. Los sitios de documentación tienen muchas partes móviles, por lo que esto funciona muy bien.

Veamos algunos ejemplos prácticos de cómo los componentes de servidor de React pueden ayudar a integrar el compilador de TypeScript en el proceso. Usaremos dos componentes de la reconocida biblioteca para ilustrar lo que los componentes de servidor de React proporcionan a la documentación. Primero, tenemos el componente de bloque de código, que se renderiza desde archivos fuente o ejemplos virtuales, los cuales serán validados contra el archivo tsconfig.json en el proyecto, como vimos al principio de esta charla.

Esos errores estaban realmente funcionando. Nota que el texto entrante aquí en el bloque de código no está formateado inicialmente, pero el componente lo formateará por ti usando Prettier. Nunca enviamos Prettier al cliente. Esto no era posible antes de los componentes de servidor de React.

Mientras usamos texto en línea aquí que podría haber venido de una fuente externa, como podemos ver en el texto literal de la plantilla aquí, también podemos renderizar bloques de código directamente desde los archivos fuente en el disco. Al mover estas preocupaciones al servidor, ganamos mucha más flexibilidad y control sobre el contenido que renderizamos mientras aseguramos que sea preciso y esté actualizado. Así que si usamos estos ejemplos directamente del código fuente, siempre estarán sincronizados inherentemente, lo cual es realmente agradable. Los ejemplos de código son geniales, pero los equipos también necesitan referencias de API como firmas de tipo, props, genéricos y qué valores predeterminados están disponibles. Aquí es donde entra el componente de referencia.

Este componente consulta el compilador de TypeScript directamente, por lo que siempre obtienes las referencias de API más precisas. La diferencia clave aquí con las herramientas de documentación tradicionales es que podemos consultar perezosamente al compilador por esta información solo cuando realmente se necesita, en lugar de pre-renderizarlo todo en un paso de construcción separado y tener que conectarlo manualmente. Incluso podemos filtrar de manera granular la información que queremos, por lo que solo incluimos lo que es relevante para el contexto actual. Esto también es realmente agradable, ya que podemos vincularlo exactamente al código fuente.

Y también para la personalización, como cualquier componente de React, podemos sobrescribir los componentes predeterminados para cambiar la apariencia o agregar funcionalidad adicional todo de manera predeterminada mientras se mantiene la precisión. Aquí es realmente donde los componentes de servidor de React comienzan a brillar. Similar a lo que siempre hemos hecho con React, ahora podemos mezclar y combinar y combinar estos componentes juntos para crear una experiencia de documentación más completa. Esto nos da mucha flexibilidad para crear una experiencia de documentación que esté adaptada a nuestras necesidades y no sacrifique precisión o mantenibilidad.