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

Rate this content
Bookmark

Recopilar piezas de información para una tarea o un proyecto es un acto derrochador y podría resultar en trabajo duplicado realizado por diferentes personas.

La incorporación, tu habilidad para mantener el código o la infraestructura y la transferencia de sistemas - La documentación juega un papel crucial en todos estos procesos.

Entonces... ¿cómo podemos escribir documentos técnicos de una manera fácil y por qué deberíamos hacerlo?


En esta charla, te mostraré una forma estructurada de escribir documentos técnicos, sin ser un escritor técnico - Así que entregarás información de gran valor a tu audiencia, a tu mejor capacidad.

Explicaré por qué deberías preocuparte por estos documentos, cómo sirven a tus mejores intereses (¡Sí, hay más de uno!) y qué gran impacto podría tener en los empleados e incluso en toda tu organización.

This talk has been presented at React Advanced Conference 2023, check out the latest edition of this React Conference.

FAQ

Hila Fish es una ingeniera senior DevOps con 15 años de experiencia en la industria tecnológica. Trabaja con Wix y es parte del Programa de Constructores de la Comunidad AWS y Embajadora de HashiCorp. Además, es coorganizadora de conferencias como DevOps Days Tel Aviv y mentora en cursos y comunidades relacionadas con DevOps.

Hila Fish destaca la importancia de la documentación técnica para compartir conocimientos, resolver incidentes rápidamente, habilitar el autoservicio, incrementar la velocidad de adopción de herramientas y evitar ser un único punto de fallo. Subraya que documentar ayuda a reducir el volumen de trabajo repetitivo y mejora la gestión del conocimiento dentro de las organizaciones.

Hila menciona varios tipos de documentos técnicos como el diseño lógico de sistemas, manuales de operaciones, readmes de código, documentos de incorporación, documentación de aprendizaje de proyectos y mensajes fijados en Slack. Estos documentos son cruciales para facilitar la comprensión y la operación dentro de los equipos técnicos.

Hila explica que una buena documentación técnica puede reducir la cantidad de consultas repetitivas a los expertos, permitiendo una mayor independencia de los equipos y reduciendo el volumen de trabajo. Por ejemplo, al documentar preguntas frecuentes y soluciones, se minimiza la necesidad de interacción directa y se agilizan las operaciones diarias.

Hila Fish recomienda conocer al público objetivo para determinar el contenido necesario, utilizar un lenguaje claro y sencillo, y estructurar los documentos de manera que sean fáciles de escanear y navegar. También sugiere incluir tablas de contenidos, utilizar enlaces internos para facilitar la navegación y destacar información importante para captar la atención rápida del lector.

Docs as Code es un enfoque que trata la documentación como código, integrando los documentos en la cadena de herramientas de desarrollo y utilizando formatos como markdown. Esto permite que la documentación sea revisada y actualizada con la misma facilidad que el código, facilitando la colaboración y el mantenimiento de la calidad de la documentación.

Hila Fish
Hila Fish
27 min
23 Oct, 2023

Comments

Sign in or register to post your comment.

Video Summary and Transcription

Esta charla enfatiza la importancia de escribir documentación técnica y proporciona consejos para mejorarla. Los documentos técnicos ayudan a explicar intenciones, razonamientos y elecciones, reduciendo el volumen de trabajo y ayudando a la resolución de problemas. Escribir documentos técnicos es importante para la visibilidad, la progresión de la carrera y la comunicación con los gerentes. Integrar la documentación en la cadena de herramientas de desarrollo y tratarla como pruebas asegura su calidad y la mantiene al día. Estructurar la documentación técnica de manera efectiva y proporcionar información concisa y clara son claves para aumentar su utilidad.

1. Introducción a la Documentación Técnica

Short description:

Hola a todos, esta charla es sobre cómo escribir una mejor documentación técnica y por qué es importante. Soy Hila Fish, una ingeniera DevOps senior en Wix con 15 años de experiencia. Creo en las comunidades y estoy involucrada en el Programa de Constructores de la Comunidad AWS y el título de Embajadora de HashiCorp. Compartamos conocimientos a través de la documentación técnica. Si no puedes automatizarlo, documéntalo. Los documentos técnicos pueden incluir diseño de sistemas, manuales de operaciones, readmes de código y documentos de incorporación.

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

2. Documentación de Aprendizaje de Proyectos

Short description:

Todos tenemos proyectos y necesitamos explicar cosas, documentar el estado y compartir conocimientos. Los mensajes fijados en Slack pueden considerarse documentos técnicos. No es suficiente que el código se documente a sí mismo. Entender el código requiere más que simplemente leerlo. Los documentos técnicos ayudan a explicar las intenciones, el razonamiento y las elecciones. Escribir documentos técnicos reduce el volumen de trabajo y ayuda a otros a entender y solucionar problemas. Permíteme darte un ejemplo. Como ingeniera DevOps, me enfrenté a preguntas repetitivas y las recopilé para referencia.

independencia, eso es genial. Documentación de aprendizaje de proyectos. Todos tenemos proyectos en nuestro día a día y necesitamos explicar cosas y tener intenciones y razonamientos y documentar el estado del proyecto, ¿verdad? Por eso tenemos la documentación de aprendizaje de proyectos también. E incluso los mensajes fijados en Slack. Esto, para mí, también se considera un documento técnico. ¿Por qué? Porque si tienes conocimientos para compartir, si algo es solo un breve comentario pero es algo que la gente usará a diario, ponlo en un mensaje fijado en Slack. Ayudará a todos. Y no estoy diciendo que tengas que practicar todos estos escenarios, pero al menos si compartes el conocimiento en uno o más de ellos, entonces estoy seguro de que estarás en un lugar mucho mejor que si no has compartido ningún conocimiento en ninguna de estas plataformas.

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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Impacto: Creciendo como Ingeniero
React Summit 2022React Summit 2022
27 min
Impacto: Creciendo como Ingeniero
Top Content
This Talk explores the concepts of impact and growth in software engineering. It emphasizes the importance of finding ways to make the impossible possible and the role of mastery in expanding one's sphere of impact. The Talk also highlights the significance of understanding business problems and fostering a culture of collaboration and innovation. Effective communication, accountability, and decision-making are essential skills for engineers, and setting goals and finding sponsors can help drive career growth. Feedback, goal setting, and stepping outside of comfort zones are crucial for personal development and growth. Taking responsibility for one's own growth and finding opportunities for impact are key themes discussed in the Talk.
Documentación Full Stack
JSNation 2022JSNation 2022
28 min
Documentación Full Stack
Top Content
The Talk discusses the shift to full-stack frameworks and the challenges of full-stack documentation. It highlights the power of interactive tutorials and the importance of user testing in software development. The Talk also introduces learn.svelte.dev, a platform for learning full-stack tools, and discusses the roadmap for SvelteKit and its documentation.
Sobre convertirse en un Tech Lead
TechLead Conference 2023TechLead Conference 2023
25 min
Sobre convertirse en un Tech Lead
Top Content
The role of a Tech Lead involves shaping the roadmap, helping the team be more effective, and working on important projects. Lessons learned include encouraging idea sharing, avoiding taking on all the work, and focusing on delegation. Tech Leads focus on the outcome, involve the team in decision-making, and make plans based on how different pieces will interact. The role of a Tech Lead is to focus on engineering and guide the team in figuring out how the whole system should fit together. Architecting can become problematic when it loses touch with the coding part, resulting in implementation issues.
Comunicación Efectiva para Ingenieros
TechLead Conference 2023TechLead Conference 2023
36 min
Comunicación Efectiva para Ingenieros
Top Content
Today's Talk covers the four building blocks of communication: people, message, context, and effective listening. It emphasizes the importance of considering the perspective of others and tailoring messages to the recipient. The Talk discusses different types and channels of communication, and the need to align them with the intended message. It also highlights the significance of soft skills in communication and provides techniques for effective communication and assessing soft skills in tech interviews. Cross-cultural communication and the impact of bluntness are explored as well.
Desarrollo impulsado por el síndrome del impostor
TechLead Conference 2023TechLead Conference 2023
31 min
Desarrollo impulsado por el síndrome del impostor
Imposter syndrome is a common experience that can lead to self-doubt and feeling like a fraud. The speaker shares their personal journey with imposter syndrome in school and throughout their career in software development. They discuss the challenges and doubts they faced, as well as the strategies they used to overcome imposter syndrome. The importance of support from managers, celebrating achievements, and sharing experiences to help others are highlighted. The talk emphasizes the need to embrace imposter syndrome and use it as a motivator for personal growth.
Puerta de entrada a React: La historia de React.dev
React Summit US 2023React Summit US 2023
32 min
Puerta de entrada a React: La historia de React.dev
The Talk discusses the journey of improving React and React Native documentation, including the addition of interactive code sandboxes and visual content. The focus was on creating a more accessible and engaging learning experience for developers. The Talk also emphasizes the importance of building a human API through well-designed documentation. It provides tips for building effective documentation sites and highlights the benefits of contributing to open source projects. The potential impact of AI on React development is mentioned, with the recognition that human engineers are still essential.

Workshops on related topic

Cómo Diseñar una Carrera Sostenible como Freelancer/Contratista
Node Congress 2022Node Congress 2022
39 min
Cómo Diseñar una Carrera Sostenible como Freelancer/Contratista
WorkshopFree
Shane Ketterman
Alexander Weekes
2 authors
¿Listo para comenzar tu carrera como freelancer o recién estás comenzando en tu viaje como freelance? Estás en el lugar correcto. Aprende los trucos del oficio de los freelancers más experimentados de la industria.
El movimiento de talento independiente es el futuro del trabajo. Si estás considerando dejar el empleo a tiempo completo para una carrera como freelancer, ahora es el momento de encontrar tu espacio exitoso en la fuerza laboral de talento independiente. Hoy en día, más personas trabajan como freelancers que nunca antes, y el mercado de freelancers contribuye con $1.2 billones a la economía de los Estados Unidos. Algunos de los roles más demandados para freelancers en este momento son desarrolladores senior con experiencia profesional en React, Python, Blockchain, QA y Node.js.
Este masterclass te ayudará a diseñar una carrera como freelancer/contratista sostenible y rentable a tiempo completo (o parcial). Te proporcionaremos herramientas, consejos, mejores prácticas y te ayudaremos a evitar errores comunes.
Diseñando una Carrera de Freelance Sostenible
React Advanced Conference 2021React Advanced Conference 2021
145 min
Diseñando una Carrera de Freelance Sostenible
WorkshopFree
Alexander Weekes
Rodrigo Donini
2 authors
¿Te gustaría perseguir tus pasiones y tener más control sobre tu carrera? ¿Te gustaría tener flexibilidad de horario y ubicación y variedad de proyectos? ¿Te gustaría tener la estabilidad de trabajar a tiempo completo y recibir un pago constante? Miles de empresas han adoptado el trabajo remoto y se dan cuenta de que tienen acceso a un grupo de talentos global. Esto es ventajoso para cualquier persona que haya considerado o esté considerando trabajar como freelance.>> Envía tu interés en convertirte en un ingeniero freelance con Toptal y recibir una llamada de un especialista en adquisición de talento <<

El trabajo freelance ya no es una elección de carrera inestable.

Este masterclass te ayudará a diseñar una carrera de freelance a tiempo completo (o parcial) sostenible y rentable. Te daremos herramientas, consejos, mejores prácticas y te ayudaremos a evitar errores comunes.
Tabla de contenidos

Módulo 1: Desmitificando los mitos comunes sobre el trabajo freelance
Módulo 2: ¿Cómo se ve el trabajo freelance en 2021 y más allá?
Módulo 3: Elecciones freelance y qué buscar (y qué evitar)
Módulo 4: Beneficios del trabajo freelance desde la perspectiva de un freelancer + estudio de caso
DESCANSO
Módulo 6: Cómo comenzar a trabajar como freelance (experiencia, currículum, preparación)
Módulo 7: Caminos comunes hacia el trabajo freelance a tiempo completo
Módulo 8: Aspectos esenciales: establecer tu tarifa y conseguir trabajo
Módulo 9: Próximos pasos: establecer contactos con colegas, mejorar tus habilidades, cambiar el mundo
Módulo 10: Preguntas y respuestas con freelancers