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.

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.

Available in English

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

Impact: Growing as an Engineer
React Summit 2022React Summit 2022
27 min
Impact: Growing as an Engineer
Top Content
Becoming a web engineer is not easy, but there are tons of resources out there to help you on your journey. But where do you go from there? What do you do to keep growing, and to keep expanding the value you bring to your company? In this talk we’ll look at the different kinds of impact you can have as a web engineer. We’ll walk through what it means to take on bigger, more complex projects, and how to scale yourself, and grow the community around you. By driving our own development we can all grow our impact, and in this talk, we’ll discuss how to go about this.
Full Stack Documentation
JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
Interactive web-based tutorials have become a staple of front end frameworks, and it's easy to see why — developers love being able to try out new tools without the hassle of installing packages or cloning repos.But in the age of full stack meta-frameworks like Next, Remix and SvelteKit, these tutorials only go so far. In this talk, we'll look at how we on the Svelte team are using cutting edge web technology to rethink how we teach each other the tools of our trade.
On Becoming a Tech Lead
TechLead Conference 2023TechLead Conference 2023
25 min
On Becoming a Tech Lead
Top Content
Tech lead sounds like a lot of work. And not the fun coding kind either. Why would you ever want that? What does it feel like when you get it?In this talk Swizec explains why he took the step towards technical leadership, how his priorities changed, and why it means he’s doing more engineering than ever. A whole new world where writing code is the easy part.
Effective Communication for Engineers
TechLead Conference 2023TechLead Conference 2023
36 min
Effective Communication for Engineers
Your communication skills affect your career prospects, the value you bring to your company, and the likelihood of your promotion. This session helps you communicate better in a variety of professional situations, including meetings, email messages, pitches, and presentations.
Imposter Syndrome-Driven Development
TechLead Conference 2023TechLead Conference 2023
31 min
Imposter Syndrome-Driven Development
“Maybe I’m fooling everyone… I’m not good enough for this, and at this point, it is a question of time until everyone figures it out” these might be the words that cross your mind as your coworker compliments you for doing another fantastic job at delivering a new feature. As you grow in your career, so does your uncertainty. You put in the extra hours, learn all the new technologies, and join all the initiatives you can, but at the end of the day, it never feels enough. At this point, that feeling is leading your actions and decisions. It is the thing that is driving your career. Only one question persists: Are you really an imposter?
Gateway to React: The React.dev Story
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The React.dev Story
A behind the scenes look at the design and development of the all-new React docs at react.dev. The new react.dev launched this year introducing new methodologies like challenges and interactive sandboxes and subtle inclusivity features, like "international tone" and culturally agnostic examples. Not only have the new docs changed how people learn React, they've inspired how we think about developer education as a community. In this talk, you will learn how the React team and some ambitious community members made the "React docs rock" for a generation of front end developers and how these new patterns and established techniques can be applied in your favorite projects.

Workshops on related topic

How To Design A Sustainable Freelance/Contracting Career
Node Congress 2022Node Congress 2022
39 min
How To Design A Sustainable Freelance/Contracting Career
WorkshopFree
Shane Ketterman
Alexander Weekes
2 authors
Ready to kickstart your freelance career or just getting started on your freelance journey? You’re in the right spot. Learn the tricks of the trade from the industry’s most experienced freelancers.
The independent talent movement is the future of work. If you’re considering leaving full-time employment for a career as a freelancer, now is the time to find your successful space in the independent talent workforce. More people are working freelance today than ever before, with the freelance marketplace now contributing $1.2 trillion to the US economy. Some of the most in-demand roles for freelancers right now are senior developers with professional experience in React, Python, Blockchain, QA, and Node.js.
This workshop will help you design a sustainable and profitable full-time (or part-time) freelancing/contracting career. We will give you tools, tips, best practices, and help you avoid common pitfalls.
Designing A Sustainable Freelance Career
React Advanced Conference 2021React Advanced Conference 2021
145 min
Designing A Sustainable Freelance Career
WorkshopFree
Alexander Weekes
Rodrigo Donini
2 authors
Would you like to pursue your passions and have more control over your career? Would you like schedule and location flexibility and project variety? Would you like the stability of working full-time and getting paid consistently? Thousands of companies have embraced remote work and realize that they have access to a global talent pool. This is advantageous for anyone who has considered or is currently considering freelance work.>> Submit your interest on becoming a freelance engineer with Toptal and get a call with Talent Acquisition specialist <<

Freelancing is no longer an unstable career choice.

This workshop will help you design a sustainable and profitable full-time (or part-time) freelancing career. We will give you tools, tips, best practices, and help you avoid common pitfalls.
Table of contents

Module 1: Dispelling common myths about freelancing
Module 2: What does freelancing look like in 2021 and beyond
Module 3: Freelancing choices and what to look for (and what to avoid)
Module 4: Benefits of freelancing from a freelancer + case study
BREAK
Module 6: How to get started freelancing (experience, resume, preparation)
Module 7: Common paths to full-time freelancing
Module 8: Essentials: setting your rate and getting work
Module 9: Next steps: networking with peers, upskilling, changing the world
Module 10: Freelancer AMA