Diseñando Documentación Efectiva: Lecciones Aprendidas Construyendo los Docs de Redux

Hola, soy Mark Erickson, y hoy estoy muy feliz de hablarles sobre el diseño de documentación efectiva, lecciones que he aprendido escribiendo la documentación de Redux. Algunas cosas rápidas sobre mí. Soy un ingeniero senior de front-end en Replay. Soy un respondedor de preguntas. Responderé preguntas prácticamente en cualquier lugar donde haya un cuadro de texto en Internet. Recolecto todo tipo de enlaces útiles e interesantes. Soy un escritor de publicaciones de blog extremadamente largas y soy un mantenedor de Redux, pero la mayoría de la gente me conoce como ese tipo con el avatar de los Simpsons.

Algunas cosas sobre la charla de hoy. Esto se va a centrar principalmente en escribir documentación para bibliotecas de software. Muchos de los consejos probablemente sean útiles para escribir documentación para otras cosas también, pero la suposición principal aquí es que estamos escribiendo documentación para el ecosistema de JavaScript. Vamos a hablar sobre algunas técnicas organizativas para escribir documentación, consejos prácticos, pensamientos sobre la escritura de tutoriales específicamente, y finalmente veremos un par de herramientas útiles de documentación.

Entonces, ¿por qué necesitamos documentación de todos modos? Un número de razones diferentes. Necesitamos poder entender qué hace una herramienta y cuándo usarla realmente. La gente necesita poder saber cómo usar una herramienta cuando no tiene ningún conocimiento previo sobre cómo funciona realmente. Puede que necesites entender preguntas específicas sobre cómo usar una herramienta y queremos poder proporcionar detalles sobre lo que contiene una API. Desafortunadamente, la realidad es que los usuarios no saben automáticamente cómo usar nuestra biblioteca y por eso necesitamos poder proporcionar esa información para ellos.

Hay una gran palabra que describe la organización de la información y esa es taxonomía. Es la ciencia de clasificar y categorizar cosas. Ahora, esto se usa principalmente en cosas como especies y anatomía física pero también se aplica a la documentación e información. Y organizar la información en taxonomías es difícil. Si alguna vez has tenido un montón de archivos en tu computadora y estás confundido sobre en qué carpeta ponerlos, has entendido el problema de intentar organizar la información.

Hay muchas maneras diferentes en las que puedes intentar organizar la documentación. Muchas categorías diferentes muchos patrones diferentes. No hay un único mejor patrón y diferentes proyectos van a tener diferentes necesidades. Habiendo dicho eso, soy un gran fan del modelo de cuatro categorías de Divio o Diataxis que divide la documentación en cuatro categorías principales. Tutoriales guías prácticas, explicaciones y referencias. Esto fue originalmente creado por alguien llamado Danielle Procida originalmente publicado bajo una empresa llamada Divio y luego fue reestructurado y se le dio el nombre de Diataxis y publicado en su propio sitio. Y hay algunas diferencias entre los dos sitios diferentes. Y no es perfecto, pero este es un muy buen punto de partida para pensar en cómo organizar realmente tu documentación.

Así que la primera categoría son los tutoriales.

Y estos están orientados al aprendizaje. El objetivo es enseñar al usuario cómo entender y usar la biblioteca paso a paso. A menudo pasando por el proceso de construir algún tipo de aplicación o proyecto real de principio a fin. Y el objetivo es enseñarles cómo usar la herramienta. Así que para cuando terminen, deberían poder comenzar a usar tu biblioteca con éxito y deberían poder pasar por las otras secciones en la documentación y realmente entender de qué están hablando las cosas.

En el caso de Redux, tenemos dos tutoriales principales. El primero es el tutorial de Redux Essentials. Y el objetivo de este es enseñar a las personas cómo usar Redux Toolkit y React Redux para construir una aplicación realista. El enfoque aquí está en el cómo. Y hablamos sobre los patrones y pasamos por muchos de los conceptos centrales, pero no siempre hablamos sobre el por qué o cómo estas abstracciones realmente funcionan internamente. Y por eso este es un tutorial muy enfocado en la práctica. Pasamos mucho tiempo construyendo características y mostrando cómo usar métodos específicos de Redux Toolkit.

Pero diferentes personas aprenden de diferentes maneras. Algunas personas quieren sumergirse y simplemente mostrarme cómo hacer esta cosa. Otras personas se sienten un poco atascadas hasta que entienden el por qué y cómo funciona esto realmente desde abajo hacia arriba. Así que también tenemos un tutorial de Redux Fundamentals. Y el objetivo de este es enseñar cada uno de los conceptos desde cero. Sin abstracciones, sin capas, sin bibliotecas. Y trabajamos desde abajo y mostramos cómo funciona realmente cada una de estas piezas. Así que es práctico en el sentido de que mostramos código real funcionando pero es un poco más teórico en el sentido de que intentamos explicar el pensamiento detrás de cada uno de estos conceptos. De hecho, muchos de los patrones comunes de Redux ni siquiera se introducen hasta tarde en este tutorial después de que ya hemos explicado lo básico. Y luego finalmente muestra cómo Redux Toolkit simplifica muchos de los patrones.

Otra categoría son las guías prácticas. Y estas están muy orientadas a objetivos. Son recetas o se centran en resolver problemas específicos. Y realmente estas van a ser cosas que solo los usuarios reales de una aplicación o una biblioteca, con algo de experiencia real, van a estar preguntando. La buena noticia sobre estas es que puedes asumir que el lector ya tiene un conocimiento y comprensión decentes y que ya conocen lo básico. Y así puedes enfocar las explicaciones en resolver este problema específico. Así que con Redux tenemos muchas guías prácticas. Tenemos cosas como cómo configurar Redux con Next.js, que tiene muchas sutilezas muy complicadas.

Tenemos una página sobre la migración de código heredado a Redux moderno. Una página sobre cómo escribir middleware personalizado, y muchas más. Estas están muy enfocadas en aquí hay un problema específico con el que podrías encontrarte si estás usando Redux y aquí está lo que necesitas saber para trabajar con ese problema de manera efectiva.

La tercera categoría son las guías de referencia. Y estas están orientadas a la información. Y probablemente se centrarán en la API de tu biblioteca y qué métodos y clases específicos y tipos están incluidos. Ahora, las guías de referencia pueden incluir ejemplos y pueden incluir uso básico. Aquí está cómo usar esta API correctamente. Eso es diferente de las guías prácticas, que se centraban en cómo lograr un resultado específico. Cada una de las diferentes bibliotecas de Redux tiene su propia sección de referencia de API.

Para el núcleo de Redux habla sobre el método create store y el tipo de store. Redux toolkit cubre métodos como configure store, create slice, create listener middleware. Y para React Redux tenemos referencias de API para los hooks modernos de Redux y el método connect heredado. Y así, cada uno de estos habla sobre cosas como cuál es el propósito de esta API, qué parámetros toma, cuáles son los valores de retorno, y luego cuáles son algunas cosas específicas que sabes cuando realmente estás usando este método. Y la categoría final de este enfoque de Divio Diataxis son las explicaciones. Y estas están orientadas a la comprensión. Está hablando sobre la visión general, el contexto de fondo, dando opiniones. ¿Cómo piensas realmente sobre este concepto en particular? Así que en el caso de Redux tenemos páginas como funciones selectoras. ¿Qué son? ¿Por qué existen? ¿Cómo funcionan? La guía de estilo de Redux que habla sobre mejores prácticas y patrones para usar Redux. O incluso la historia de Redux que habla sobre su creación y su evolución a lo largo del tiempo. Ahora hay muchas categorías de documentación que no encajan perfectamente en estas cuatro. Por ejemplo, tu proyecto va a tener un archivo readme. Y esta es realmente la primera introducción a un proyecto. Es lo que la gente verá cuando miren el repositorio de GitHub o miren un paquete en npm. Y así probablemente debería tener algo de información sobre ¿qué es este proyecto? ¿Cómo te configuras? Un enlace a la documentación real. Tal vez algunas otras piezas útiles también.

Páginas de FAQ que tienen respuestas a preguntas muy específicas sobre el uso de la biblioteca. Esto es un poco como una guía de uso o un cómo hacer. Pero también tal vez un poco más centrado en preguntas literales. Las notas de lanzamiento son muy importantes. Cada vez que lanzas una nueva versión de tu biblioteca la gente quiere saber, ¿cuán grande es este cambio? ¿Existe el riesgo de que alguno de mis códigos se rompa? ¿Qué ha cambiado? Poder ver los problemas en los PRs que realmente se cambiaron también. Estos son todos tipos de documentación y no necesariamente caen en esas cuatro categorías de las que hablamos antes. Así que las taxonomías son difíciles.

trabajando en la documentación de Redux. Si tengo información específica sobre cómo usar correctamente los tipos de TypeScript o algunos ejemplos de uso específicos, ¿deberían ir en las páginas de referencia de API para estos métodos? ¿O deberían ir bajo una categoría de uso completamente separada?

En la documentación de Redux tenemos una sección de uso y francamente tenemos algunas páginas allí que probablemente sean más de un cómo hacer y algunas de ellas que son más de una sección de explicación. ¿Realmente ambas van bajo uso? ¿Qué pasa con las cosas que son puramente informativas? ¿Deberíamos tener una categoría de comprensión separada para esas? ¿Y qué tipo de categoría es una página de FAQ de todos modos? Nuevamente, no hay respuestas específicas pero estas son las cosas en las que tienes que pensar mientras intentas organizar la información en la documentación.

Algunos consejos adicionales para escribir documentación. Uno es tener en cuenta al lector objetivo. Realmente ayuda saber quién va a estar leyendo estas páginas de documentación. ¿Cuál es su nivel de experiencia? ¿Qué quieren saber de esto? Así como qué vas a asumir como su trasfondo. Tu documentación no puede explicar todo y cada página de documentación va a asumir ciertas cantidades de conocimiento.

Ya sea cosas que deberían saber de otras páginas de la documentación ya o cosas que tienes que asumir que saben antes de siquiera mirar tu documentación en absoluto. Así que es muy útil hacer que el conocimiento previo sea muy claro desde el principio. En el caso de los tutoriales de Redux, tengo que asumir que muchos de nuestros lectores van a ser personas que acaban de salir de un bootcamp. Tal vez han tenido un mes de JavaScript, un mes de React, un mes de Redux. Adelante. Así que tengo que asumir que están bastante frescos.

Al mismo tiempo, no podemos pasar tiempo en nuestra documentación explicando cómo usar JavaScript y HTML en React. Así que claramente indicamos que estos son requisitos previos. Asumimos que ya conoces estas cosas. Incluso proporcionamos algunos enlaces a recursos sobre dónde aprender estos temas y de esa manera no tenemos que gastar tiempo y contenido explicando estas cosas en nuestros tutoriales. También es muy útil repetir la información varias veces en diferentes secciones de la documentación. Ayuda a señalar las cosas desde el principio que dicen que esta página va a cubrir estos temas y luego al final tener un resumen que realmente resuma las cosas que explicaste en esta página.

Además, cubre el mismo tema en múltiples áreas de la documentación de diferentes maneras. Los usuarios podrían estar leyendo los tutoriales y aprender de esa manera. Podrían venir con una pregunta específica sobre un concepto o un término. Y así tener la información cubierta de múltiples maneras aumenta la posibilidad de que realmente encuentren la información que quieren aprender. En el caso de Redux, tenemos múltiples páginas que hablan sobre lógica asíncrona y obtención de datos y thunks. Lo cubrimos en el tutorial de Essentials donde hablamos sobre el método createAsyncThunk y damos solo los detalles necesarios sobre qué es un thunk, pero nos enfocamos más en cómo usar este método correctamente. El tutorial de Fundamentos de Redux entra en más detalle sobre el middleware y cómo funciona y el concepto de usar middleware para efectos secundarios. Y luego tenemos una página de uso llamada Writing Logic with Thunks que habla específicamente sobre el nombre y el concepto y patrones que podrías ver al usar Thunks. Así que hay algo de superposición en la información entre estas páginas, pero todas son muy relevantes.

Las páginas de FAQ son un concepto útil, pero también pueden ser sobreutilizadas. Cuando realmente agregas información y respondes preguntas en una página de FAQ, vale la pena intentar ver cómo puedes realmente agregar eso a otras secciones de la documentación también.

a otras secciones de la documentación también. De esa manera las personas podrían estar leyendo un tutorial y verlo y aprender un concepto particular y luego podrían realmente nunca tener que ir a la página de FAQ en primer lugar porque de alguna manera aprendieron eso naturalmente en el proceso de lectura. Por otro lado, sigue siendo útil tener enlaces específicos a FAQs para que puedas dirigir a las personas a ese conocimiento directamente. Para bibliotecas que están escritas en TypeScript, tienes que decidir si tu documentación va a ser escrita TypeScript primero o JS primero. Y esto cubre tanto las referencias de API como los tutoriales. De hecho, acabo de terminar de renovar el tutorial de Redux Essentials para que sea TypeScript primero. Siempre tuve preocupaciones sobre que fuera una capa extra de conocimiento que los principiantes tendrían que manejar al intentar aprender Redux, pero en última instancia queremos que nuestros usuarios usen Redux, usen TypeScript con Redux. Y así que puse mucho esfuerzo este año para renovar el tutorial, hacer que la aplicación de ejemplo sea TypeScript de principio a fin, enseñar TypeScript en el contenido del tutorial. Y realmente queremos que las personas usen TypeScript con Redux. Ahora a veces en secciones como las referencias de API, si intentas mostrar a los lectores los tipos reales de TypeScript para tu biblioteca, podrían no ser muy útiles, especialmente si esos tipos son complejos o muy derivados. Así que a veces podrías necesitar escribir tipos falsos de TypeScript que sean más simples y fáciles de leer para alguien cuando están mirando la referencia. TypeScript te permite tener buena información en la sección de JS doc para un método. Y eso puede ser extraído y embebido directamente en tu sitio de documentación. De manera similar, también es bueno asegurarse de que los bloques de ejemplo estén realmente actualizados con el código actual que está en el repositorio. Y puedes realmente compilar esos durante el paso de construcción de la documentación.

Y así para ambos, los bloques de documentación y el paso de compilación, usamos un paquete que fue creado por mi co-mantenedor, Lenz Weber, llamado Remark TypeScript Tools, que usamos el compilador de TypeScript para compilar fragmentos así como dar las pestañas de alternancia de TypeScript JavaScript en las referencias también. Algunas cosas rápidas sobre escribir tutoriales. Como dije antes, el tutorial de Redux Essentials es el tutorial principal que queremos para aprender Redux. Los llevamos de cero a construir una aplicación práctica. Y lo hacen construyendo una pseudo-aplicación de redes sociales, como un pequeño Facebook, un poco de Twitter. Tiene más de 53,000 palabras en este punto. Me han dicho que debería escribir un libro, y básicamente lo hice. Y hubo muchos desafíos al hacer esto. Cuando estás escribiendo un tutorial, quieres que la aplicación de ejemplo sea lo suficientemente realista y práctica como para que el lector sienta que realmente está haciendo algo, pero no puede ser tan compleja que se distraigan y se atasquen con conceptos y código irrelevantes. También es muy difícil averiguar cómo enseñar los conceptos en el orden correcto, pero todo debería seguir sintiéndose como una progresión natural mientras estamos construyendo esta aplicación. Tenemos que asumir que habrá una ruta de aprendizaje lineal, que el lector va a pasar por todo de principio a fin. Y luego algo con lo que luché es para TypeScript. ¿Hacemos todo en JavaScript y luego mostramos la capa de TypeScript al final, o hacemos TypeScript todo el camino? Así que lo que tenemos es ocho secciones, 53,000 palabras, que comienzan con conceptos básicos, muestran un ejemplo de aplicación de contador independiente donde podemos señalar todas las diferentes piezas y cómo se conectan entre sí. Y luego las partes tres a ocho construyen una aplicación práctica paso a paso, donde vamos desde agregar la tienda de Redux, escribir la primera slice, despachar la primera acción, todo el camino hasta los selectores y la obtención de datos y terminando con RTK Query para realmente construir aplicaciones reales. En mi proceso, y esto no será cierto para todos, pero lo que hice fue idear la aplicación de ejemplo, construí la versión final desde cero yo mismo, y luego de alguna manera hice ingeniería inversa. Si iba a construir la aplicación y hacer los cambios con el tiempo, ¿qué conceptos querría enseñar y en qué orden querría enseñarlos?

Y luego volví a través de ese contenido de código y escribí las explicaciones del tutorial real que decían, primero vamos a agregar una tienda de Redux, luego vamos a agregar una slice, luego vamos a agregar este formulario. Y construí todo desde allí.

Unos cuantos consejos rápidos para tutoriales, intenta encontrar maneras de mantener al lector involucrado. Si puedes agregar ejercicios interactivos o desafíos, definitivamente vale la pena hacerlo. Y los documentos de React son un gran ejemplo de esto, con desafíos interactivos y tutoriales sandbox justo en el medio. Los diagramas son buenos, el formato para resaltar texto o conceptos específicos es muy útil. Si puedes agregar sandboxes en la página que muestren tanto la aplicación en ejecución como el código que la impulsa en ese momento, eso es muy útil. Enlaza a otras páginas de documentación, tal vez has introducido un concepto, das una breve explicación, pero enlazas a una guía de uso o una página de cómo hacer que da más detalles. O agrega secciones de explicación detallada expandibles.

Dice, aquí está la información básica sobre un concepto que acabamos de introducir y si quieres más detalles, puedes expandir esto y luego tener unos cuantos párrafos más. De esa manera el lector no se abruma, pero la información está ahí si quieren verla. Y definitivamente haz que las cosas sean revisadas. Cuando terminé con mi reciente renovación del tutorial de Redux Essentials, un par de personas fueron lo suficientemente amables como para revisar todo de principio a fin y me dieron una retroalimentación muy valiosa sobre explicaciones que no estaban claras o cosas que podrían mejorarse y eso hizo que el resultado final fuera mucho mejor. Finalmente, aunque hay muchas maneras de escribir documentación hoy en día, el patrón más común es escribir el contenido como Markdown y luego usar un generador de sitios estáticos para generar la documentación. Me gusta mucho Docusaurus, es una herramienta excelente, es lo que usamos para todos los sitios de documentación de Redux. Pero hay muchas otras buenas herramientas por ahí. Starlight y MKDocs son populares. Y si no quieres escribir Markdown, entonces Notaku se puede usar para generar sitios desde páginas de Notion.