Documentación Técnica - ¿Cómo puedo escribirla mejor y por qué debería importarme?

Hola a todos, muchas gracias por unirse a mi charla sobre la documentación técnica. Y esta charla será sobre cómo puedo escribir la documentación técnica mejor y por qué debería importarme? Por supuesto, también me refiero a ustedes. Pero primero que nada, hola, mi nombre es Hila Fish, soy una ingeniera senior DevOps y trabajo con Wix. Tengo 15 años de experiencia en la industria tecnológica. Soy una firme creyente de las comunidades y es por eso que soy parte del Programa de Constructores de la Comunidad AWS y también hablo mucho sobre Terraform, por eso obtuve el título de Embajadora de HashiCorp. Soy coorganizadora de conferencias en Israel, donde vivo, DevOps Days Tel Aviv es la más grande de todas. Soy mentora en cursos y comunidades, Amiga de la Cultura DevOps. Creo que esto es lo que ayuda a las empresas a lograr grandes cosas. Y en mi tiempo libre, soy la cantante principal en una banda de covers, como pueden ver en esta foto, lo cual es muy divertido. Así que creo, y realmente creo, que cualquiera puede y debería escribir documentos técnicos, porque en el... por supuesto, les daré muchos ejemplos más adelante. Pero un ejemplo que me viene a la mente es el hecho de que en medio de la noche, si tengo un incidente crítico del que debo ocuparme, y es en un territorio desconocido, algo con lo que no estoy familiarizada porque es algo que, digamos, mi compañero de equipo estaba manejando la mayor parte del tiempo. Tengo este incidente crítico. No sé qué hacer. Ni siquiera sé por dónde empezar. Si tengo un manual de operaciones que me ayuda a solucionar el problema, o al menos me dice que necesito revisar esto y aquello, estoy contenta. Así que realmente no me importa. Y si tengo este manual de operaciones, no me importa si el inglés es fabuloso o un inglés roto. Realmente no me importa. Mientras tenga un manual de operaciones que me ayude a debug o solucionar el problema, eso es todo lo que me importa. Así que lo más importante aquí es compartir el conocimiento, y por eso todos deberíamos escribir documentación técnica. Así que siempre me gusta decir que si no puedes automatizarlo, documéntalo. Y muchas de las cosas que podemos hacer y compartir en nuestro día a día pueden considerarse documentos técnicos. Así que la primera cosa principal que es directa es el diseño lógico del sistema o un resumen, pero también los manuales de operaciones, como acabo de mencionar. Excelentes documentos técnicos que nos ayudan a resolver incidentes mucho más rápidamente. Readmes de código. Necesitamos explicar el código spaghetti o cualquier cosa que se relacione con el código, entonces un readme de código es un buen lugar para empezar. Documentos de incorporación. ¿Por qué asignar un compañero para ayudar a tu nuevo miembro del equipo si puedes crear documentos de incorporación y dejar que el nuevo miembro del equipo se incorpore por sí mismo y luego pueden hacerlo ellos mismos. Tienen este sentido de

Así que esta es la parte donde realmente me gusta interactuar con la audiencia y hacer esta pregunta. Estás lejos en tu computadora pero te lo preguntaré y necesitas ser honesto contigo mismo. ¿Has oído o dicho esta frase antes? Mi código se documenta a sí mismo. Mucha gente me lo ha dicho, y, ya sabes, no me mientas, o has oído o has dicho esta frase antes, estoy completamente seguro de ello. La gente decía, simplemente lee el código y entiende de qué se trata. O el código cuenta la historia. No, no es el caso. Nunca es el caso. Necesitas entender cosas que van más allá de simplemente el código. Por ejemplo, si el código es spaghetti code, entonces buena suerte entendiendo el código. Pero cualquier otra cosa como por qué elegimos esto o aquello o cualquier intención, razonamiento detrás de escribir el código como es, necesitamos documentation que nos ayude a lograr eso. Así que realmente entendamos por qué escribir documentos técnicos.

En primer lugar, para reducir tu volumen de trabajo. Y cuando digo reducir tu volumen de trabajo, quizás puedas preguntarme, espera, ¿reducir? Pero si me siento y paso dos horas escribiendo documentos técnicos, no estoy reduciendo. Estoy sobrecargando mi volumen de trabajo, ¿verdad? Así que permíteme darte un ejemplo para explicar. Yo, como ingeniera DevOps, trato con mucha gente. Ayudo a mucha gente, desarrolladores, ingenieros de QE, todo tipo de personas. Y en mi trabajo anterior, venían a mí y me hacían preguntas repetitivas. No todos sabían cómo usar Kubernetes con fluidez. Así que decían, oye, ¿cómo soluciono un error en Kubernetes? ¿O qué es este error? Y cosas así. Así que básicamente, recopilé todas las preguntas repetitivas.

Y entonces creé un documento. Lo llamé consejos y trucos por DevOps. Creé este documento con explicaciones y respuestas a todas estas preguntas repetitivas. Y entregué este documento a su custodia.

Antes del documento, me abordaban siete u ocho veces al día. Fui abordado siete u ocho veces al día por Devon QA. Después de publicar este documento, se redujo a una o dos veces al día. Así que esto es lo que quise decir con reducir tu volumen de trabajo. Realmente te ayuda a largo plazo, lo cual es genial.

Otra cosa. Habilitación de autoservicio e incremento de la velocidad. Así que uno de los proyectos que hice en una empresa anterior es migrar de un gran cubo cloud a un GitLab autoalojado. Y entonces todos los desarrolladores necesitan trabajar con GitLab. No conocen GitLab. Necesitan tener como una incorporación suave para conocer la herramienta. Así que creé un documento sobre cómo usar GitLab de una manera mucho más concisa de lo que encontrarán en línea. Y realmente les ayudó a adoptar la herramienta más rápido y ayudó con la velocidad en general.

Otros ejemplos de documentos de incorporación que acabo de mencionar antes también ayudan con la habilitación de autoservicio. Los documentos de resolución de problemas, también son buenos para eso. E incluso un bot de Slack para ayudar con las respuestas a preguntas y respuestas en Slack podría definitivamente ayudar con el autoservicio e incrementar la velocidad. Eliminar incidentes de producción más rápido porque como mencioné antes, si tengo libros de ejecución de guardia que me ayudan a resolver un problema, también podría ayudar a disminuir el MTTR, tiempo medio hasta la resolución, ayudar a la empresa a cumplir con los SLA y ayudarte a volver a dormir mucho más rápido. Así que esta es otra razón por la que hacerlo.

Otra razón, evitar un único punto de fallo o un cuello de botella, que eres tú. Porque te haré esta pregunta retórica, ¿quieres irte de vacaciones y seguir estando disponible para las llamadas de trabajo? ¿O quieres irte de vacaciones con la mente despejada? Así que lo diré aquí, la seguridad laboral está muerta. Por favor, comparte el conocimiento. Y algunas personas dicen que la IA se llevará nuestros trabajos de todos modos. Así que luchemos contra eso compartiendo conocimientos. También ayudará a aclarar las cosas para ti o para el futuro tú, porque una vez que estructuras las cosas y las escribes de una manera clara, también se organizará en tu mente. Y también cualquier cosa relacionada con intenciones, razonamiento, cualquier cosa que no sea directa, como ayudar a cualquier cosa, cualquier ayuda que pueda ayudarte a gestionar sistemas y demás, debería ser documentada porque si implementas algo ahora en un año, no recordarás nada. Así que deberías documentarlo para ayudarte, al futuro tú, y también por supuesto, a otros miembros del equipo o a otras personas que necesiten lidiar con esos sistemas.

Visibilidad, atraerá la atención a las cosas que haces en el trabajo, lo que a su vez te ayudará a progresar en tu career. Y también ayudará a comunicar cosas a tus gerentes, el alcance de tu trabajo, que realmente eres un jugador de equipo, porque si escribes documentation técnica, significa que te preocupas por tus compañeros de equipo y quieres compartir el conocimiento. Y realmente transmitirá que eres un jugador de equipo y no solo un eslogan que escribes en el CV.

Y último pero no menos importante, ayudará a entender ¿por qué hacemos las cosas de cierta manera? Esto es cierto para ser un ingeniero en general. Necesitamos defender las decisiones que estamos tomando y comunicarlas a los demás. También desarrollará tu mentalidad de negocio y te hará un mejor ingeniero porque siempre preguntar por qué siempre resultará en que te esfuerces por la mejor solución o implementación posible. Así que estos son solo ejemplos de ello. ¿Por qué establecí certificados aquí y cómo renuevo los certificados? ¿Por qué el modelo es complejo y no sigue las prácticas de código sencillo y cosas así? Así que cualquier cosa que pueda ayudarte a entender ¿por qué hacemos las cosas de cierta manera y ayudarte a defender las decisiones que estás tomando también es una cosa muy importante para documentar. Y también ¿por qué no? ¿Por qué la gente documenta código abierto y repositorios y tiene más sentido que documentar nuestras intenciones y decisiones, ¿verdad? Así que siempre deberíamos esforzarnos por hacer eso y no solo las cosas directas como documentar código abierto o repositorios.

Bueno, realmente espero que te haya convencido hasta ahora de que es realmente importante escribir documentos técnicos. Así que veamos cómo lo hacemos sin que sea una carga, sin tener que decir que, hey, no soy un escritor técnico, así que puedo hacerlo. Puedes hacerlo incluso sin ser un escritor técnico y voy a mostrarte un proceso estructurado de cómo escribir documentos técnicos de una manera fácil que puedes seguir y luego podrás escribir documentos técnicos en tu día a día. Así que en primer lugar, necesitas conocer a tu público. Basándote en tu público, sabrás qué necesita ser cubierto y hasta qué punto. Este es, por cierto, tu momento para planificar y escribir en puntos lo que vas a cubrir en tu documento si no puedes escribirlo ahora y luego podrás recordarte a ti mismo lo que vas a cubrir. Así que tenemos documentos para uso interno como design de sistemas, etc. y uso externo. Documentation de API para tus usuarios, etc. Así que para uso interno, mantenedores, ¿sobre qué escribes? Cosas en las que trabajaste mientras trabajabas en ellas porque recordamos las cosas mejor cuando están frescas en nuestras mentes, así que documenta estas partes ahora mismo y de nuevo, si no puedes, al menos añádelas como puntos para que recuerdes cubrirlas más tarde. Cosas que te molestan para que otras personas no se encuentren con ellas también. Te daré un ejemplo. En la migración que hice de Bitbucket Cloud a GitLab autoalojado, abrí muchos tickets de soporte a GitLab durante la migración y luego abrí un ticket tres o cuatro días después porque aún no estaba en producción así que no están obligados a responder inmediatamente. Y tres o cuatro días después, por favor proporciona logs. Estoy como, vale, proporciono logs y luego de nuevo, tres o cuatro días, necesito esperar. Abrí otro ticket. Lo mismo pasó entonces. Como, no importa qué tipo de ticket abro, siempre piden los mismos logs y la forma de recoger los logs siempre es la misma. Ejecutas un comando en la CLI y recoge los logs para ti. Así que en la visión general de GitLab, un documento que creé para mi equipo para poder gestionar el GitLab después de que me vaya, no solo después de que me vaya, incluso cuando estoy allí, pero en el documento, realmente documenté cómo abrir un ticket de soporte sin tener este ping-pong entre nosotros y el soporte. Así que he escrito que abres un ticket en este portal de soporte. Recoges los logs por adelantado, ejecutas el comando CLI X y luego abres el ticket junto con los logs.

De esta manera, evitas el ping-pong. Todos están contentos. Evitas que otras personas se encuentren con cosas molestas y ahorras tiempo en el proceso. Cosas que no están claras o son directas.

Entonces, otro ejemplo de GitLab. Durante la implementación, elegí implementar una versión de database del lado de GitLab, que es diferente de la versión predeterminada que está en el gráfico de ayuda. ¿Por qué hice eso? Tenía una muy buena razón para hacerlo. Entonces necesito documentarlo. ¿Por qué hice eso? Porque si no, si no lo estoy documentando y alguien mirará el código después de que me haya ido, revisarán el código o querrán actualizar GitLab y luego tal vez revertirán mi decisión, pero tenía una muy buena razón por la que lo hice. Entonces necesitas documentarlo para explicar realmente las cosas y nuevamente defender las decisiones que estás tomando. Entonces este es un ejemplo. Por supuesto, otros ejemplos son si el código no está claro, necesitas explicar el flujo. Estamos describiendo funciones reales y cosas así.

¿Sobre qué escribes? Para uso externo, para usuarios o consumidores. Entonces escribe de qué se trata, posibles casos de uso y comienzos rápidos, cualquier peculiaridad, problemas y cosas a considerar mientras usas este X y cualquier ejemplo, tanto simple como complejo que ayudará a tu usuario a adoptar lo que sea de lo que estás escribiendo de la manera más fácil posible y tan robusta como sea posible porque es fácil cubrir solo ejemplos simples, pero también necesitas cubrir los complejos para ayudar a tu usuario a hacer lo que necesite y no solo abandonarlo porque parece complicado de integrar.

La siguiente fase de la escritura de un documento técnico es decidir o cumplir con el tipo de documentation. Entonces algunas personas no tienen capacidad de decisión en su empresa, y no pueden influir en la votación y simplemente necesitan seguir el tipo de documentation que tienen. Entonces, a veces las empresas tienen documentos en conocimientos basados como Confluence. Entonces simplemente necesitan seguir con eso. Pero si tienes alguna capacidad de decisión cualquier influencia que puedas tener en la decisión, realmente recomiendo pasar a Docs as Code. Lo cubriré en un momento, pero en general, significa interactuar con los documentos en tu IDE. Los documentos están completamente integrados en la cadena de DevTools y no necesitas salir de tu IDE para escribir documentos, lo cual es bueno para nuestros desarrolladores. Pero hablaremos más sobre Docs as Code más tarde.

Algunas pautas de contenido generales que necesitas seguir, que deberías seguir en tu documentation. Entonces, en primer lugar, deberías tener una tabla de contenidos. Es esencial para el descubrimiento de contenido. ¿Y por qué es eso? Por el flujo de usuario. En realidad encontré un artículo de 1997 que decía que las personas no leen, escanean. Y con, ya sabes, cómo es estos días que las personas, su capacidad de atención es incluso menor, es cierto ahora más que nunca. Entonces este es el flujo de usuario.

El usuario busca algo, cualquier palabra clave que le ayude a encontrar lo que está buscando. Por eso deberías tener títulos y subtítulos significativos. Luego encuentran algunos ejemplos, algunos resultados. Escanean los resultados. Si encontraron lo que están buscando, genial, van al resultado. Si no, necesitan ir y navegar en otro lugar. Por eso deberías tener enlaces en tu documento que ayudarán a tu usuario a encontrar lo que está buscando.

Puedes pensar en tu documentation como microservices. Cada documento se sostiene por sí mismo, pero puede interactuar con otros documentos. O no realmente interactuar, pero puede relacionarse con otros documentos. Digamos que tienes cómo hacer documentos X y luego quieres enlazar a otro, como si quisieras leer más sobre el sistema, aquí está el enlace. Y luego tienes enlaces y la gente puede enlazar y navegar a estos documentos y luego esperamos encontrar lo que están buscando. Por eso, siempre deberías tener enlaces en tu documentation para cualquier otro contenido que el usuario pueda encontrar útil.

Resalta, pon cosas en negrita porque de nuevo, la gente pasa rápidamente y escanea los documentos y no los están leyendo al máximo, así que ayúdales a hacer eso. Y utiliza colores en la medida de lo posible. Algunos dicen que sería controvertido porque algunas personas son daltónicas menos y problemas de accessibility y cosas así, en mi experiencia, encontré útil poner cosas buenas en verde, cosas malas o cosas de las que hay que estar al tanto en rojo y luego cosas a considerar o pensar en naranja. Cuando utilicé eso, entonces el desarrollador dice, ah, bien, ahora lo noté. Así que si tiene sentido, utiliza colores también. Palabras y frases. Utiliza palabras cortas y más frases en lugar de palabras más largas y menos frases porque de esa manera ayudará a las personas a pasar rápidamente por el documento de manera mucho más rápida y eficiente. Y por favor, por favor, por favor, no intentes ser Shakespeare, ¿vale? Escribe en inglés americano simple que los hablantes no nativos de inglés pueden entender fácilmente.

Así que vamos a cubrir Docsys Code. Docsys Code básicamente es documentation que está escrita en markdown. Y es increíble porque todavía te permitirá tener una tabla de contenidos y resaltados e incluso colores. Es texto plano, por lo que es legible para los humanos. Es fácil de escribir y diferenciar. Y es agnóstico a la plataforma, lo que significa que puedes integrarlo donde quieras. No importa qué plataforma estás utilizando, qué IDE estás utilizando. Puedes usarlo como quieras. La carpeta de documentos está en el mismo repositorio de código.

Así que los documentos están integrados en la cadena de herramientas de desarrollo y no hay necesidad de salir del IDE cada vez que estás escribiendo una documentation. Puedes utilizar la revisión de PR para asegurarte de que la calidad del documento está en un estado de alta calidad y el documento realmente existe. Porque si, por ejemplo, un desarrollador añadió una porción de código que no cubrió en la documentation, puedes fallar el PR y decir, hey, no añadiste una condición a eso. Así que no te permitimos fusionar el PR hasta que añadas una documentation.

Así que tanto para comprobar la existencia de la condición como para comprobar la calidad del documento. ¿Y qué quiero decir con calidad? Puedes hacer todo tipo de comprobaciones como las mismas para CICD para aplicaciones. Puedes hacer CICD para documentation también para comprobar cualquier validación de que no hay enlaces rotos, linters, cualquier cosa parecida. Hay dos herramientas de las que puedo hablar. No las he probado yo mismo. Sólo vi demos, pero parecen prometedoras. DocuSource, que también te permite empujar código a un frontend para ver los documentos en un portal de UI. Y también permite la versioning de documentos y cosas así. Y Swim, es en realidad una empresa israelí. También permite muchas características. Así que estos son sólo dos ejemplos que conozco, pero puedes, por supuesto, buscar en línea cualquier otra opción que te pueda ayudar con CICD y te ayude a automatizar la creación de documentos y el mantenimiento de documentos en el día a día.

Y como puedes ver a la derecha, una guía de estilo de Google dice que los documentos prosperan cuando se tratan como pruebas. Una tarea necesaria que uno aprende a saborear porque recompensa con el tiempo. Definitivamente recompensa con el tiempo. Mucha gente dice que lo más, lo doloroso en la documentation es asegurarse de que no están obsoletos y siempre se mantienen al día. Así que si introduces pruebas y te aseguras de que son parte del proceso de PR, entonces puedes asegurarte de que el documento siempre estará al día. Y eso será útil para cualquier usuario que lea la documentation. Una tercera fase de la escritura de la documentation técnica, recuerda a tu público. Así que recuerdas que dijimos que necesitas conocer a tu público. Ahora necesitas recordarlos. Ten en cuenta el flujo de usuario en y entre secciones y ordena los documentos desde los más utilizados hasta los más tempranos. Así que por ejemplo, ¿adivina qué voy a mencionar ahora? Correcto, la documentation de GitLab. Así que me dio mucho material bueno para esta presentación. Así que espero que esta sea la última vez que lo recuerde, pero nunca se sabe. Así que la documentation de GitLab que he escrito, tenía, como dije, documentos para que los desarrolladores lo adoptaran, pero también documentation para mi equipo para ayudarles a gestionar el sistema en sí. Así que empecé la documentation por cómo actualizar porque GitLab lanzó help charts cada mes o así.

Básicamente, eso fue lo más destacado y lo más frecuente que sabía que los miembros de mi equipo harían para actualizar la versión. Así que cómo actualizar, lo empecé primero. Y luego los certificados, los renovarán solo una vez cada dos años. Así que eso fue lo siguiente. Respaldo y monitoreo, de nuevo, necesitas hacerlo solo una vez que configuras un GitLab por primera vez. E integraciones, teníamos integraciones con Jenkins, con Jira. También lo haces solo por primera vez que configuras un Jenkins. Y luego, por supuesto, tenía el soporte y cómo evitar el ping pong en el soporte. Así que estructuré el documento desde el más utilizado hasta el raramente utilizado. Porque de nuevo, la gente ojea el documento. Quería ayudarles a hacerlo de manera más eficiente y encontrar lo que necesitan encontrar más rápidamente. Esto es muy importante. Concepto versus tareas. Necesitas pensar en lo que tu público quiere y básicamente dárselo y no confundir entre los dos. Así que si tu público quiere saber algo, AKA conceptos, necesitas tener documentos que cubran información, antecedentes, explicaciones, razonamientos, intenciones, etc. Pero si quieren hacer algo, AKA tareas, entonces el documento debería ser un cómo hacer. Y no confundas entre los dos, los conceptos versus las tareas. Pon un enlace al otro tipo para ayudar a los otros usuarios a encontrar lo que necesitan rápidamente. Porque en cualquier momento dado, un usuario quiere hacer solo una cosa. Quieren saber algo o quieren hacer algo. Realmente es raro que el usuario quiera hacer dos cosas a la vez. Así que permíteles lograr eso. Quieren hacer algo, tienen solo un documento de cómo hacer. Y luego en el documento tienen enlaces a si quieres saber más sobre el sistema, aquí está la información, aquí están los antecedentes, aquí están las explicaciones, etc. Así que es muy importante no confundir los dos y tener un documento delgado para un solo propósito, saber o hacer. Básicamente la última fase de la escritura de un documento técnico es compartirlo con otros. Necesitas tener un bucle de retroalimentación porque lo que es sencillo para nosotros que estamos escribiendo la documentation, lo que es sencillo para nosotros no es necesariamente el caso para nuestros lectores. Necesitan decir, hey, tal vez, ¿qué son esas iniciales? No sé sobre ellas, o me falta algún contexto, o esta frase que tal vez pensaste que es muy sencilla, pero realmente no entiendo lo que querías decir aquí. Así que el bucle de retroalimentación es muy, muy importante porque ¿por qué escribimos una documentation para que otros la lean, ¿verdad? Así que si el documento actualmente no es útil, necesitamos tener un bucle de retroalimentación para saber cuáles son los problemas con nuestra versión actual de nuestra documentation, y luego solucionarlo y tener iteraciones para mejorar la documentation y saber que la última iteración es la más útil para nuestros usuarios. Y comencé esta presentación diciendo que no tienes que ser un escritor técnico para escribir documentación técnica, pero si quieres perfeccionar tu inglés, si quieres tener una mejor calidad en inglés, o como escribir para tu documentación técnica, puedes escanear este código QR.

Recopilé algunos tips de un colega, olvidé la palabra, un colega mío, un escritor técnico, Joshua Shulgasser, y algunos tips que seleccioné yo mismo. Así que creo que encontrarás algunos tips que te ayudarán a mejorar tu documentation si así lo deseas.

Básicamente eso es todo, y quizás dirías, hey, no soy un escritor técnico y no recuerdo nada de lo que acabas de decir en esta presentación. Al menos lleva contigo esta regla de oro, proporciona a los lectores la información que necesitan y devuélvelos a su tarea lo más pronto posible. La conversación siempre debe ser clara, simple y al grano. Lo que escribes es muy útil y ayuda siempre y cuando sea conciso y claro. Así que asegúrate de hacerlo porque de nuevo, la gente siempre escanea, no lee. Así que ayúdales a lograr lo que necesitan lo más rápido posible.

Y para los gerentes de ustedes, y básicamente no es solo para gerentes. Haré una aclaración en un segundo. Si quieres asegurarte de que la documentation es una parte integral de la tarea y no la tienes actualmente, y quieres lograrlo ahora mismo, porque tomará tiempo adoptar una herramienta que te ayude con CICD y la gestión de PR, cosas así. Así que si quieres lograrlo ahora mismo y asegurarte de que la documentation es parte integral de la tarea, entonces ten una definición de tarea realizada. Una vez que se añadió la documentation, entonces se te permite cerrar el ticket. Y luego esperamos que se herede en los desarrolladores o cualquier otra persona que tenga estas tareas y necesiten incorporar documentation. Tendrán esta noción de, hago lo que necesito como parte de la tarea. Creo una documentation y luego cierro el ticket. Y luego esperamos que este proceso te ayude a lograr una documentation actualizada incluso sin incorporar herramientas en este momento.

Así que espero que ahora después de esta presentación, volverás a tu escritorio, escribirás algo de documentation, actualizarás algo de documentation y luego podrás decir que tu código ahora está bien documentado. Muchas gracias.