Archivos de la categoría Comunicación

Evita frustrar aún más a tus usuarios con tu documentación

Escribir documentación es una de las habilidades más importantes de un desarrollador.

JustSimply.dev:

Si alguien ha llegado a buscar algo que has escrito en Google, significa que está atascado. Estar atascado puede ser frustrante y molesto. Así que trata de no hacer que se sienta peor diciéndole lo fácil que debería ser encontrar lo que busca. Esto puede obstaculizar su capacidad para aprender lo que quieres que aprenda.

Es probable que tengas la tentación de que al escribir documentación sobre tus proyectos, quieras usar palabras como “sencillo”, “fácil”, “simplemente”, “nada más”.

Se entiende. Lo que quieres es contarle a tu usuario lo mucho que estás haciendo por él o ella, resaltando lo poco que tienen que hacer para resolver su problema ahora que va a utilizar tu solución.

Desafortunadamente, con lo que tu lector se va a quedar es con un sentimiento de frustración e insuficiencia, pues en lo que ha estado atorado todo este tiempo, resulta ser “fácil” de resolver.

Tenemos que ser más cuidadosos y compasivos al momento de escribir documentación. Si alguien la está consultando, es porque quiere aprender algo más. Lo menos que podemos hacer es procurar que las personas que nos leen no se queden con la idea de que, dhu, lo que estás buscando es OBVIO.

El Triángulo de la Documentación de Código

Hace un tiempo propuse que deberías escribir código que se documente solo, y luego agregarle documentación. En el artículo original, escribí:

La idea de que “tu código debería de documentarse solo” no es un get out of jail free card para no documentar tu código. Las ocasiones en tu carrera profesional donde escribir documentación no agrega valor a tu trabajo son muy pocas. Tan pocas, de hecho, que no se me viene ninguna a la mente. ¿Tal vez cuando estás trabajando en un proyecto propio? Pero hasta Damian Conway dijo que “la documentación es una carta de amor que le escribes a tu yo del futuro”.

Hoy me encontré una idea que aumenta mi punto: El Triángulo de la Documentación de Código.

Este modelo mental nos dice que toda pieza de código está documentada en 3 dimensiones distintas, cada una respondiendo una pregunta muy particular.

  • ¿Qué?: Tu código, en sí, explica lo que estás haciendo.
  • ¿Por qué?: Los comentarios que le agregas a tu código, explican tu proceso de toma de decisiones y la razón de tus soluciones.
  • ¿Cómo?: El contexto dentro del cual estás desarrollando tu programa; la descripción original del problema.

Si te enfocas en escribir código que “se documente solo”, en un futuro no sabrás por qué llegaste a esa solución, ni cómo esa solución es apropiada para el problema original.

Recuerda, agregar documentación a tu código (en forma de comentarios, glosarios, RFCs, pruebas, etc.), no es una admisión que no fuiste lo suficientemente inteligente para escribir “buen” código, sino un acto de compasión. Demuestra tu interés porque la siguiente persona que modifique tu código pueda enfocarse en agregar valor al proyecto — y, muy probablemente, esa siguiente persona vas a ser tú.

3 consejos para que mejores tu Inglés

¡Escucha Inglés para Devs! Un podcast donde Darwin Pinto me explica cómo pronunciar un término de la industria del software, y yo le explico lo que significa. Miles de personas lo escuchan en Spotify.

Trabajar en la industria del software es un acto de balance entre mejorar tus habilidades técnicas y tus soft skills.

Como probablemente sabes, el lenguaje por defecto en tecnología es el Inglés. Así que es de vital importancia que, cuanto antes, aprendas a comunicarte en ese lenguaje. No estoy diciendo que si no hablas Inglés no podrás trabajar en esto. Pero sí estoy diciendo que si sabes comunicarte en el lenguaje universal de la tecnología, desarrollarte profesionalmente será una tarea mucho más sencilla.

Como publiqué hace un tiempo, hablar Inglés ya no es una ventaja competitiva. Es igual (o más importante, algunos argumentan) que saber programar bien.

Si no sabes por donde comenzar, aquí te dejo algunos tips que comparto cada vez que alguien me pregunta sobre este tema. Estos tips me ayudaron personalmente, y he visto cómo también han ayudado a muchas personas a sobrepasar la barrera del Inglés.

[convertkit form=2572581]

Lo que importa es que la idea llegue lo menos golpeada posible

Primero aclaremos algo: no es necesario que hables Inglés perfecto. Con que logres comunicar la idea de manera eficiente es suficiente. Si encima de ello logras dominar las inflexiones, expandir tu léxico y neutralizar tu acento, estarás en el 1% de la población que no habla Inglés como su primera lengua.

El lenguaje, la comunicación, es una cualidad imperfecta. Al contrario de un lenguaje de programación, que puedes aprender leyendo un manual, el Inglés (o cualquier otro lenguaje) no tiene un proceso de evolución determinado por una organización. Cada quién habla su propia versión del Inglés, y lo único que te toca es intentar apegarte lo más posible a las reglas gramaticales y fonéticas. Todo lo demás es un producto secundario del que lo está hablando, cómo lo aprendió y lo que quiere comunicar.

Pregúntale a cualquier persona que haya trabajado para un cliente que hable Inglés, o que trabaje en una empresa estadounidense. El día a día de trabajar con personas hablando Inglés es una batalla constante por descifrar qué es lo que están diciendo.

Sucede lo mismo con el Español, por cierto. Como lo aprendiste desde muy pequeña, sientes que lo dominas y ahora te tomas ciertas libertades para comunicar ideas. Porque lo que importa no es que lo hables perfecto, sino que la otra persona entienda lo que le quieres decir. Estos “atajos“ están determinados por el contexto dentro del cual te desarrollas. Así, mandar código a producción se dice “deployear“, cerrar un Pull Request se dice “mergear“ y eliminar los problemas de tu programa se vuelve “debuggear“. ¿Crees que alguien que no domina el Español va a entender de qué estás hablando?

Así que no seas tan dura contigo misma. Y si estás pensando que las personas que trabajan en E.E.U.U. hablan un Inglés perfecto, no podrás estar más lejos de la realidad.

Groovy!

Exponte a situaciones reales

Nadie nunca va a hablar como los audios que te ponía tu maestra en el curso de listening. Quítate esa idea de la cabeza.

El día al día de trabajo usando Inglés se trata, como ya te dije, de descifrar qué es lo que realmente está sucediendo. Y mientras esos audios son una herramienta bastante buena para aprender la manera correcta de pronunciar una palabra, la verdad es que en el día a día no importa tanto como crees. La cosa es que difícilmente vas a lograr desarrollar la habilidad de entender cómo realmente se comunica una persona normal en Inglés si no te expones a situaciones que lo propicien.

La ventaja de estar vivo en 2021 es que ya no necesitas viajar a Estados Unidos para mejorar tu Inglés. Hoy en día es tan fácil como suscribirte a un podcast y escuchar hablar a dos amigos de la infancia, uno de Boston y otro de Ohio, e intentar descifrar qué es lo que están diciendo. ¿Cómo habrías podido vivir esa experiencia hace 20 años? Viviendo un año en Boston, otro en Ohio, y luego inventándote la conversación en tu cabeza.

Algunas personas recomiendan películas o audiolibros. Y aunque ciertamente no puede perjudicarte escucharlos, me gustaría que quedara claro que no son situaciones reales. Los medios que están producidos para las masas están, justamente, producidos. Son artificiales.

Pero un podcast entre dos amigos rara vez va a estar cuidado para que todo mundo le entienda. Y ahí es justo donde sucede la magia.

Identifica un tema que te llame la atención, busca un podcast en Inglés que hable de ello, and go to town.

Práctica, práctica, práctica…

Y para terminar, el consejo principal de este artículo: práctica.

Práctica, práctica, práctica.

Cualquier músculo por no ejercitarse se atrofia. Y el Inglés no es una excepción. Ojalá fuera así de fácil, y que pudieras estudiar algo una vez sin olvidarlo jamás.

Este consejo ata los otros tips en uno solo. Atrévete a escribir y hablarlo sin preocuparte de si está perfecto o no, y hazlo en situaciones lo más parecidas a la realidad posible.

  • Escribe en foros, participa en conversaciones de comunidades adeptas a tu área.
  • Escribe blog posts o documentación en Inglés.
  • Únete a un grupo de Discord de tu videojuego favorito y comenta.
  • Comparte tus opiniones en proyectos de código abierto.
  • Haz entrevistas de práctica.
  • Acuerda con alguna amistad que los jueves únicamente se van a hablar en Inglés.

El chiste es no quitar el dedo del renglón.

Y sí, puede ser que te cueste trabajo al inicio, pero ¿qué cosa que valga la pena no cuesta trabajo? Tú puedes.

P.D. — Escucha Inglés para Devs en Spotify.

Por qué te cuesta aceptar nuevas ideas: el efecto Semmelweis

En algún momento de la historia, los médicos no se lavaban las manos antes y después de atender pacientes. Como podrás imaginarte, esto daba como resultado muchísimos contagios y muertes innecesarias.

En 2021 eso sería considerado negligencia médica. En el siglo 19 era simplemente como se hacían las cosas.

Ignaz Semmelweis descubrió, por ahí de 1847, que la tasa de mortalidad se reduciría 10 veces si los médicos se lavaran las manos después de atender un paciente, y antes de atender a otro. Sugirió que los cirujanos usaran una solución clórica para limpiarse.

Él comenzó a realizar esta práctica, y sus pacientes dejaron de enfermar. Aunque aún no había “una ciencia” que avalara su propuesta (la teoría bacteriana de la enfermedad no se descubriría por otros 20 años), sí había suficiente evidencia empírica para soportar su teoría: lavarse las manos entre pacientes salvaba vidas.

A pesar de esto, miembros del gremio médico decidieron ignorarlo. No solo eso, sino que lo rechazaron y buscaron desacreditarlo públicamente. En ocasiones, las justificaciones de su rechazo eran por ideas que ni siquiera tenían que ver con la medicina.˙ Por ejemplo, algunos genuinamente creían que “las manos de un caballero no podrían transmitir enfermedades”.

A este fenómeno social se le conoce hoy en día como el efecto Semmelweis. Es la reacción involuntaria de rechazar nuevas ideas, datos o evidencia que no concuerde con nuestro sistema de creencias — por más evidencias o pruebas que existan.

Todos en alguna ocasión hemos rechazado una idea al instante, solamente para darnos cuenta, para infortunio de nuestro ego, de que era completamente válida. Ganar conciencia del efecto Semmelweis es importante — especialmente para nosotras, las personas con Cerebro de Programador™, que pensamos que todo en esta vida se trata de lógica y relaciones lineales. Creemos que nuestra vida se basa en evidencia y hechos, cuando la realidad es que muchas de las decisiones que tomamos en el día a día vienen desde nuestro sistema de creencias.

La próxima vez que sientas el impulso de rechazar una idea, pregúntate: ¿la estás rechazando porque no hay suficiente evidencia? ¿O porque esa idea no cabe dentro de tu sistema de creencias?

Haz código que no necesite documentación. Y documéntalo.

Los programadores tenemos tendencias egocéntricas.

Entendemos (o creemos entender) cómo funcionan las computadoras. Y eso nos hace sentir especiales. Y si somos tan especiales para entender cómo funcionan las computadoras, cualquier persona que no entienda mi código no es tan especial como yo.

Documentar qué estás haciendo, y por qué, puede ser un golpe al ego. Pero uno que vale la pena. Que documentes algo no es una admisión que no fuiste lo suficientemente inteligente para escribir “buen” código, sino un acto de compasión. Demuestra tu interés porque la siguiente persona que modifique tu código pueda enfocarse en agregar valor al proyecto — y muy probablemente esa siguiente persona seas tú.

La idea de que “tu código debería de documentarse solo” no es un get out of jail free card para no documentar tu código. Las ocasiones en tu carrera profesional donde escribir documentación no agrega valor a tu trabajo son muy pocas. Tan pocas, de hecho, que no se me viene ninguna a la mente. ¿Tal vez cuando estás trabajando en un proyecto propio? Pero hasta Damian Conway dijo que “la documentación es una carta de amor que le escribes a tu yo del futuro”.

Escribir documentación no tiene que ser aburrido ni estar limitado a únicamente escribir comentarios.

En orden de accesibilidad, puedes escribir:

  1. comentarios en tu código.
  2. READMEs
  3. glosarios
  4. RFCs o documentos de diseño
  5. pruebas
  6. Documentos de arquitectura

Te invito a que veas la documentación como un tema de accesibilidad, y no de exactitud. ¿Qué opinarías de alguien que dice que no debería haber rampas en las banquetas de una ciudad porque no necesita caminar para transportarse? Reflexiona.

Comunicación síncrona: ¿qué es, cuándo usarla y por qué?

La comunicación síncrona usualmente sucede a través de medios que yo llamo “efímeros”. Este tipo de medios favorece la velocidad en la que los mensajes pueden ser transmitidos sobre cualquier otro factor.

La comunicación síncrona se caracteriza porque requiere que todas las partes involucradas estén prestando atención a lo mismo durante el mismo periodo de tiempo. Como con HTTP 1.1, que la conexión entre el cliente y el servidor debe de mantenerse vigente para que el mensaje pueda llegar de un lugar a otro. Si uno de los dos componentes deja de poner atención, la conexión se termina y el mensaje no es comunicado.


El protocolo HTTP 1.1 requiere que ambas partes se mantengan en sintonía para que el mensaje pueda ser comunicado correctamente.

Los medios de comunicación síncrona son usualmente efímeros. Es decir, que solamente “existen” mientras están siendo usados. Una llamada telefónica, por ejemplo, se podría considerar un medio de comunicación síncrono:

  • Todas las partes necesitan poner atención a la llamada para que esta sea productiva.
  • Si uno de las dos partes cuelga el teléfono, la comunicación se termina.
  • Esa llamada en particular únicamente existe mientras está sucediendo. Al terminarse no es posible volver a tener esa misma llamada. (Se podría volver a tener la misma conversación, pero no la llamada.)

Existen muchos medios de comunicación síncronos a tu disposición. Es importante que aprendas a identificarlos y a usarlos de manera adecuada. Aquí hay algunos otros ejemplos de medios de comunicación síncrona que te podrás encontrar en tu carrera:

  • Conversaciones de pasillo.
  • Mensajes instantáneos (Slack, Google Chat, Teams, WhatsApp, Telegram).
  • Videoconferencias (Google Meet, Whereby, Zoom).
  • Sesiones de pair programming.

¿Cuándo debes usar la comunicación síncrona?

Por lo general se utilizan medios de comunicación síncrona cuando el mensaje es relevante únicamente durante un periodo de tiempo. Un ejemplo de esto es cuando se quiere notificar de algún evento, como que una tarea se terminó en tiempo y forma.

Lo que debes de considerar al momento de comunicar algo a través de medios síncronos, es que el riesgo de que ese mensaje se pierda y no vuelva a ser encontrado es bastante alto. Por lo general, deberías de evitar utilizar medios de comunicación síncronos asumiendo que la información que compartas va a poder ser recuperada después.

Aunque algunos medios de comunicación síncronos, como los mensajes directos, tienen la habilidad de buscar información pasada, la realidad es que no están diseñados para esto. La mayoría de estas herramientas están diseñadas con la conveniencia en mente, no con la consigna de que deberían de ser un acervo de información hacia el futuro.

De manera más concisa, está bien usar medios de comunicación síncronos si…

  • El mensaje que quieres comunicar es relevante únicamente durante un marco de tiempo definido. Es decir, no importará si ese mensaje se pierde en el éter, porque de todos modos únicamente aportaba valor si se consumía al momento en que lo enviaste. Ejemplo: “ya va a comenzar la llamada”.
  • Existe un sentido de urgencia de tu parte. Por ejemplo, en caso de que tengas una emergencia porque el servicio está caído, es mucho más práctico llamar por teléfono a la persona de DevOps para que apoye que enviarle un correo (asíncrono) para notificarle.
  • No estás tomando decisiones que impacten de manera estructural el futuro del proyecto o del equipo. Por ejemplo, ¿tú y tu equipo están intentando decidir qué librería de linting van a utilizar en el proyecto? Discutirlo en un chat grupal está bien — es una conversación. Pero si estás intentando decidir qué topología de red se va a instalar en un edificio, esta conversación debería de ser llevada en medios que estén diseñados para preservar la información a largo plazo.

Combinando la comunicación síncrona y la asíncrona

Algo que debes de tomar en cuenta es que una conversación que inicia de manera síncrona tiene la capacidad de convertirse en asíncrona, si así se requiere. Y de hecho, siempre que estés comunicando algo a través de medios síncronos, deberías de poner mucha atención si algo de lo que se está compartiendo debería preservarse.

Notificar que un proyecto se completó de manera exitosa es claramente información apta para ser comunicada síncronamente. Puedes hacerlo a través de Google Chat o Slack. Sin embargo, el historial y resumen de entrega del proyecto completado es información que se debe de preservar, y por lo tanto deberías de preservarlo en una carpeta compartida de Google Drive o Dropbox. 

Lo anterior es un ejemplo de cómo, para el mismo propósito, combinarías la comunicación síncrona y la asíncrona.

La comunicación siempre está en flujo

No siempre será posible utilizar el medio correcto para compartir lo que quieres. Y está bien. Eres humano.

Lo importante, más allá de que utilices tal o cual aplicación para comunicar algo, es que comiences a generar la conciencia de que no solamente importa qué dices, sino cómo lo dices y a través de qué medio. Sobre todo si estás en una posición de liderazgo, pues cómo tú comunicas pone la pauta para el resto del equipo. Y créeme, no hay nada más complejo que intentar ponerle orden a la comunicación de un equipo de un día para otro.

Ejercitar tu músculo para saber si estás usando el medio adecuado para comunicarte con tu equipo es uno de los pasos que debes de tomar para mejorar tu carrera profesional. Hacerlo no solamente te abrirá los ojos a un mundo de empatía más allá del código, sino que te hará mucho más digno de confianza ante tu equipo. Sabrán que tú, más que un miembro más de la banda, serás una pieza catalizadora de organización y orden.