Escritura técnica para desarrolladores

HTML, CSS, JavaScript, Python, PHP, C++, Dart: ¡hay tantos lenguajes de programación por ahí y es posible que incluso domines varios de ellos! Pero a medida que nuestro objetivo es escribir más y mejor código, la forma en que escribimos y nos comunicamos en el lenguaje cotidiano se vuelve cada vez más importante... y quizás incluso se pasa por alto.

Podría decirse que la forma en que escribimos sobre y alrededor del código es tan importante como el propio código. Y a pesar de dónde se encuentre en esa línea, todos podemos estar de acuerdo en que nuestras palabras tienen el potencial tanto de ayudar como de dañar la efectividad del código.

En este artículo, quiero describir cómo estos dos campos aparentemente distintos (programación y escritura) pueden unirse y llevar nuestras habilidades de desarrollador al siguiente nivel.

Espera, ¿redacción técnica? Sí, eso es exactamente lo que quiero decir. Realmente creo que todos somos escritores en un sentido u otro. Y estoy aquí para brindarle una introducción con sugerencias, consejos y ejemplos de escritura sobre cómo puede convertirlo en un mejor desarrollador y comunicador.

La escritura técnica está en todas partes

El año pasado, el equipo detrás del popular cliente Mac Git, Tower, encuestó a más de 4,000 desarrolladores y descubrió que casi el 50% de ellos pasaban entre 3 y 6 horas al día escribiendo código.

Y sí, esa es una encuesta que sondea a un grupo bastante especializado, pero me imagino que muchos de nosotros estamos en algún lugar de ese rango. Cualquiera que sea el caso, un desarrollador no escribe código las 24 horas del día, los 7 días de la semana, porque, como sugiere esta encuesta, dedicamos mucho tiempo a otras cosas.

Eso podría incluir:

• demostrando una nueva característica,
• documentando esa nueva característica,
• actualizar un ticket de trabajo relacionado con esa nueva característica, o
• trabajo atrasado para respaldar esa nueva función.

Por supuesto, siempre hay tiempo para ir al baño y también para Wordle.

De todos modos, la mayoría de las cosas que normalmente hacemos implican comunicarnos con personas como su equipo, colegas, clientes, usuarios y otros desarrolladores.

Así que pasamos una buena parte de nuestro tiempo comunicándonos con humanos a través de palabras además de la comunicación que tenemos con las computadoras a través de código. Las palabras son lenguaje escrito. Y si escribimos mejor nuestras palabras, nos comunicaríamos mejor. Cuando nos comunicamos mejor, es más probable que consigamos lo que queremos.

Eso es Escritura Técnica 101.

Y ni siquiera termina aquí. A algunos programadores también les gusta hacer sus propios productos, lo que significa que necesitan hacer que el marketing sea parte de su trabajo. La escritura técnica también juega un papel muy importante en eso. Así que sí. Creo que es bastante justo decir que la escritura técnica es en efecto en todas partes.

¿Qué es una buena gramática?

Con tantos lenguajes de programación, lo último que queremos es aprender otro.

Gramática es una parte integral del inglés y desbloquea todo el potencial de la comunicación. Nos hace más formales, profesionales y coherentes.

Déjame darte un resumen rápido sobre el lenguaje.

la sintaxis inglesa

Al igual que los lenguajes de programación, el inglés tiene una sintaxis bien definida y comienza con palabras.

Las palabras son los componentes básicos del inglés y se dividen en ocho cubos:

Piense en estos como UI componentes: son piezas modulares que puede mover para construir una oración completa y sólida, de la misma manera que puede armar una oración completa y sólida UI. ¿Todos los componentes deben estar allí todo el tiempo? ¡Ciertamente no! Arma una oración con las piezas que necesitas para completar la experiencia, tal como lo harías con una interfaz.

Voz y tono

Vocabulario, puntuación, estructura de oraciones y selección de palabras. Estos son todos los ingredientes del inglés. Los usamos para compartir ideas, comunicarnos con nuestros amigos y familiares y enviar correos electrónicos a nuestros compañeros de trabajo.

Pero es crucial considerar la sonar de nuestros mensajes. Es sorprendente cómo un signo de exclamación puede cambiar por completo el tono de un mensaje:

1. Me gusta programar.
2. I como ¡programación! :)

Es fácil confundir la voz con el tono y viceversa.

Voz es lo que concierne a nuestra elección de palabras, que depende del contexto. Por ejemplo, es más probable que un tutorial para principiantes use jerga y lenguaje informal para transmitir una voz amigable, mientras que la documentación puede escribirse de manera formal, seria y profesional en un esfuerzo por ir directo al grano.

Un mismo mensaje, escrito con dos voces diferentes:

• Diversión: "Expanda su red social y manténgase actualizado sobre las tendencias actuales".
• Grave: "Encuentre trabajos en una de las aplicaciones de redes sociales y mercado de trabajo en línea más grande".

No es inusual escribir accidentalmente mensajes que parecen condescendientes, ofensivos y poco profesionales. Aquí es donde tono entra en juego. Lee tus mensajes en voz alta, haz que otras personas los lean por ti y experimenta con la puntuación y la estructura de las oraciones. Así es como perfeccionas tu tono.

Aquí hay otra forma de pensarlo: tu voz nunca cambia, pero tu tono sí. Tu voz es similar a quién eres como persona, mientras que el tono es cómo respondes en una situación determinada.

Voz activa y pasiva

Una oración siempre contiene un actor, un verbo y un objetivo. El orden en que estos vienen determina si la oración está escrita en voz activa o pasiva.

El actor es el primero en un voz activa. Por ejemplo: "CSS pinta el fondo".

Las oraciones que usan una voz activa son más sencillas que sus contrapartes. Son más claros, más breves y más comprensibles, perfectos para una voz más profesional que va directo al grano.

Con una voz pasiva, el actor es el último. (¿Ves lo que hice allí?) Eso significa que nuestro actor, CSS en este caso, llega al final así: "El fondo está pintado por CSS".

Los lectores suelen convertir una voz pasiva en una voz activa en sus cabezas, lo que resulta en más tiempo de procesamiento. Si alguna vez has escuchado que escribir en voz activa es mejor, esta suele ser la razón. Los escritores de tecnología prefieren la voz activa la mayor parte del tiempo, con muy pocas excepciones, como citar investigaciones: "Se ha sugerido que..."

Pero eso no significa que siempre debas esforzarte por tener una voz activa. Cambiar de uno a otro, incluso en el mismo párrafo, puede hacer que su contenido fluya sin problemas de una oración a otra si se usa de manera efectiva.

Evitando errores

La gramática tiene que ver con la estructura y la corrección del lenguaje, y no hay nada mejor para lograrlo que una revisión rápida de su documento. Es muy importante deshacerse de sus escritos de errores de ortografía, problemas de gramática e imperfecciones semánticas.

Al final de este artículo, te mostraré las herramientas invaluables que usan los profesionales para evitar errores de escritura. Obviamente, hay correctores ortográficos incorporados en casi todo en estos días; nuestros editores de código incluso tienen complementos de corrección ortográfica y de pelusa para ayudar a prevenir errores. 

Pero si está buscando una herramienta integral para todo lo relacionado con la gramática, Gramaticalmente es una de las herramientas más utilizadas. No voy a recibir un soborno por eso ni nada. Es simplemente una gran herramienta que muchos editores y escritores usan para escribir contenido limpio y claro, similar a cómo puede usar Emmet, eslint o cualquier otro linter para escribir código limpio y claro.

Escribir comentarios de código

Las cosas que escribimos para otros desarrolladores pueden tener un gran impacto en la calidad general de nuestro trabajo, ya sea lo que escribimos en el código, cómo explicamos el código o cómo damos retroalimentación sobre una parte del código.

Es interesante que cada lenguaje de programación viene con un conjunto estándar de funciones para escribir un comentario. Deberían explicar qué está haciendo el código. Con eso, no me refiero a comentarios vagos como este:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

En su lugar, utilice comentarios que proporcionen más información:

red *= 1.2 // Apply a 'reddish' effect to the image

Se trata de contexto. “¿Qué tipo de programa estoy construyendo?” es exactamente el tipo de pregunta que deberías hacerte.

Los comentarios deben agregar valor

Antes de ver qué hace un comentario de código "bueno", aquí hay dos ejemplos de comentarios perezosos:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Recuerde que el propósito de un comentario es agregar valor a un fragmento de código, no repetirlo. Si no puede hacer eso, es mejor que deje el código como está. Lo que hace que estos ejemplos sean "perezosos" es que simplemente reafirman lo que obviamente está haciendo el código. En este caso, los comentarios son redundantes porque nos dicen lo que ya sabemos: ¡no agregan valor!

Los comentarios deben reflejar el código actual

Los comentarios desactualizados no son raros en proyectos grandes; me atrevo a decir en MEJOR DE TU proyectos.

Imaginemos a David, un programador y un tipo genial con quien pasar el rato. David quiere ordenar una lista de cadenas alfabéticamente de la A a la Z, por lo que hace lo obvio en JavaScript:

cities = sortWords(cities) // sort cities from A to Z

Luego, David se da cuenta de que sortWords() en realidad ordena las listas de la Z a la A. Eso no es un problema, ya que simplemente puede invertir la salida:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Desafortunadamente, David no actualizó su comentario de código.

Ahora imagina que no te conté esta historia, y todo lo que viste fue el código de arriba. ¡Naturalmente, pensaría que después de ejecutar esa segunda línea de código, las `ciudades` se ordenarían de la Z a la A! Todo este fiasco de confusión fue causado por un comentario obsoleto.

Si bien este puede ser un ejemplo exagerado, algo similar puede suceder (y a menudo sucede) si está compitiendo contra una fecha límite cercana. Afortunadamente, esto se puede prevenir siguiendo una regla simple... cambie sus comentarios al mismo tiempo que cambia el código.

Esa es una regla simple que le ahorrará a usted y a su equipo muchos deuda técnica.

Ahora que sabemos cómo se ven los comentarios mal escritos, veamos algunos buenos ejemplos.

Los comentarios deben explicar el código unidiomático

A veces el natural forma de hacer las cosas no es la correcta. Es posible que los programadores tengan que "romper" los estándares un poco, pero cuando lo hacen, es recomendable dejar un pequeño comentario que explique su razón de ser:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Eso es útil, ¿verdad? Si usted fue responsable de revisar este código, es posible que haya tenido la tentación de corregirlo sin que ese comentario explique qué sucede.

Los comentarios pueden identificar tareas futuras

Otra cosa útil que hacer con los comentarios es admitir que hay más trabajo por hacer.

// TODO: use a more efficient algorithm
linearSort(ids)

De esta manera, puede mantenerse enfocado en su flujo. Y en una fecha posterior, usted (u otra persona) puede regresar y arreglarlo.

Los comentarios pueden enlazar con la fuente.

Entonces, acaba de encontrar una solución a su problema en StackOverflow. Después de copiar y pegar ese código, a veces es bueno mantener un enlace a la respuesta que lo ayudó para que pueda volver a consultarla en el futuro.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Esto es importante porque las soluciones pueden cambiar. Siempre es bueno saber de dónde vino tu código en caso de que alguna vez se rompa.

Escribir solicitudes de extracción

Solicitudes de extracción (PRs) son un aspecto fundamental de cualquier proyecto. Se encuentran en el corazón de las revisiones de código. Y las revisiones de código pueden convertirse rápidamente en un cuello de botella en el desempeño de su equipo sin una buena redacción.

Una buena PR descripción resume qué se está haciendo un cambio y porque se está haciendo. Los proyectos grandes tienen una plantilla de solicitud de extracción, como esta adaptada de un ejemplo real:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Evite vago PR títulos

Por favor, evite títulos que se vean así:

• Arreglar la construcción.
• Arreglar error.
• Añadir parche.

Estos ni siquiera intento para describir con qué compilación, error o parche estamos lidiando. Un pequeño detalle adicional sobre qué parte de la compilación se corrigió, qué error se eliminó o qué parche se agregó puede ser de gran ayuda para establecer una mejor comunicación y colaboración con sus colegas. Nivela y pone a la gente en la misma página.

PR Los títulos se escriben tradicionalmente en tiempo imperativo. Son un resumen de una línea de todo el PRy deben describir qué está siendo realizado por el PR.

A continuación, presentamos algunos buenos ejemplos:

• Admite atributos de srcset personalizados en NgOptimizedImage
• Configuración de imagen predeterminada a 75% de calidad de imagen
• Agregue selectores explícitos para todos los ControlValueAccessors incorporados

Evite largas PRs

Una gran PR significa una descripción enorme, y nadie quiere revisar cientos o miles de líneas de código, ¡a veces solo para terminar descartando todo!

En cambio, podrías:

• comunicarse con su equipo a través de Temas,
• hacer un plan,
• dividir el problema en partes más pequeñas, o
• trabajar en cada pieza por separado con su propio PR.

¿No es mucho más limpio ahora?

Proporcione detalles en el PR cuerpo

A diferencia de la PR título, el cuerpo es las lugar para todos los detalles, incluyendo:

• Porque es el PR ¿Siendo hecho?
• ¿Por qué es este el mejor enfoque?
• Cualquier deficiencia en el enfoque e ideas para resolverlas si es posible.
• El número de error o ticket, los resultados de referencia, etc.

Informar errores

Los informes de errores son uno de los aspectos más importantes de cualquier proyecto. Y todos los grandes proyectos se basan en los comentarios de los usuarios. Por lo general, incluso después de innumerables pruebas, son los usuarios los que encuentran la mayoría de los errores. Los usuarios también son grandes idealistas y, a veces, tienen ideas sobre características; por favor escúchalos!

Para proyectos técnicos, todo esto se hace mediante informes de problemas. Un problema bien escrito es fácil de encontrar y responder para otro desarrollador.

Por ejemplo, la mayoría de los grandes proyectos vienen con una plantilla:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Recopilar capturas de pantalla

Capture el problema usando su utilidad de captura de pantalla del sistema.

Si es una captura de pantalla de un CLI programa, asegúrese de que el texto sea claro. si es un UI programa, asegúrese de que la captura de pantalla capture los elementos y estados correctos.

Es posible que deba capturar una interacción real para demostrar el problema. Si ese es el caso, intente grabar GIF usando una herramienta de grabación de pantalla.

Cómo reproducir el problema

Es mucho más fácil para los programadores resolver un error cuando está en vivo en su computadora. Es por eso que una buena confirmación debe venir con los pasos para reproducir con precisión el problema.

Aquí hay un ejemplo:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Sugerir una causa

Usted es quien atrapó el error, por lo que tal vez pueda sugerir algunas posibles causas de por qué está allí. Tal vez el error solo ocurra después de que te encuentres con un determinado evento, o tal vez solo ocurra en el móvil.

Tampoco está de más explorar el código base y tal vez identificar qué está causando el problema. Luego, su Problema se cerrará mucho más rápido y es probable que se le asigne a la PR.

Comunicarse con los clientes

Puede trabajar como autónomo en solitario, o tal vez sea el desarrollador principal de un pequeño equipo. En cualquier caso, supongamos que es responsable de interactuar con los clientes en un proyecto. 

Ahora, el estereotipo del programador es que somos malos comunicadores. Se sabe que usamos una jerga demasiado técnica, les decimos a otros lo que es y no es posible e incluso nos ponemos a la defensiva cuando alguien cuestiona nuestro enfoque.

Entonces, ¿cómo mitigar ese estereotipo? Pregunte a los clientes qué quieren y siempre escuche sus comentarios. Así es como se hace.

Haz las preguntas correctas

Comience por asegurarse de que usted y el cliente estén en la misma página:

• ¿Cual es tu público objetivo?
• ¿Cuál es el objetivo del sitio?
• ¿Quién es su competidor más cercano y qué están haciendo bien?

Hacer preguntas también es una buena manera de escribir de manera positiva, particularmente en situaciones en las que no está de acuerdo con los comentarios o la decisión de un cliente. Hacer preguntas obliga a esa persona a respaldar sus propias afirmaciones en lugar de atacarla defendiendo su propia posición:

• ¿Está de acuerdo con eso incluso si viene con un costo de rendimiento adicional?
• ¿Mover el componente nos ayuda a lograr mejor nuestro objetivo?
• Genial, ¿quién es responsable de mantener eso después del lanzamiento? 
• ¿Sabe de antemano si el contraste entre esos dos colores pasa los estándares WCAG AA?

Las preguntas son mucho más inocentes y promueven la curiosidad sobre la animosidad.

Vendete a ti mismo

Si está haciendo un lanzamiento a un posible cliente, necesitará convencerlo para que lo contrate. ¿Por qué el cliente debería elegirte? Es importante especificar lo siguiente:

• Quien eres
• Que haces
• Por qué eres un buen candidato para el trabajo
• Enlaces a trabajos relevantes que ha realizado

Y una vez que obtenga el trabajo y necesite redactar un contrato, recuerde que no hay contenido más intimidante que un montón de jerga legal. Aunque está escrito para proyectos de diseño, el Asesino a sueldo puede ser un buen punto de partida para escribir algo mucho más amigable.

Su atención a los detalles podría ser la diferencia entre usted y otro desarrollador que intenta ganar el mismo proyecto. En mi experiencia, los clientes contratarán fácilmente a un desarrollador con el que creen que disfrutarán trabajando que al que es técnicamente más competente o experimentado para el trabajo.

Microcopia de escritura

Microcopia es el arte de escribir fácil de usar UI mensajes, como errores. Apuesto a que ha habido momentos en los que usted, como desarrollador, tuvo que escribir mensajes de error porque se pusieron en un segundo plano hasta el momento del lanzamiento.

Esa puede ser la razón por la que a veces vemos errores como este:

Error: Unexpected input (Code 693)

Los errores son lo último con lo que desea que se enfrenten sus usuarios. Pero suceden, y no hay nada que podamos hacer al respecto. Aquí hay algunos consejos para mejorar sus habilidades de microcopia.

Evite la jerga técnica

La mayoría de la gente no sabe qué es un servidor, mientras que el 100% de los programadores sí. Es por eso que no es inusual ver términos poco comunes escritos en un mensaje de error, como API o "ejecución de tiempo de espera".

A menos que esté tratando con un cliente técnico o una base de usuarios, es probable que la mayoría de sus usuarios no hayan tomado un curso de informática y no sepan cómo funciona Internet y por qué algo en particular no funciona. Por lo tanto, el error.

Por lo tanto, un buen mensaje de error no debería explicar porque algo salió mal, porque tales explicaciones podrían requerir el uso de términos técnicos aterradores. Por eso es muy importante evitar el uso de jerga técnica.

Nunca culpes al usuario

Imagina esto: estoy tratando de iniciar sesión en tu plataforma. Así que abro mi navegador, visito su sitio web e ingreso mis datos. Luego me dicen: "Tu correo electrónico/contraseña es incorrecto".

Aunque parezca dramático pensar que este mensaje es hostil, inconscientemente me hace sentir estúpido. Microcopy dice que nunca está bien culpar al usuario. Intente cambiar su mensaje a algo menos puntiagudo, como este ejemplo adaptado del inicio de sesión de Mailchimp: “Lo siento, esa combinación de correo electrónico y contraseña no es correcta. Podemos ayudarlo a recuperar su cuenta”.

¡También me gustaría agregar la importancia de evitar TODO EN MAYÚSCULAS y signos de exclamación! Claro, se pueden usar para transmitir entusiasmo, pero en microcopia crean una sensación de hostilidad hacia el usuario.

No abrumes al usuario

¡Usar humor en tu microcopia es una buena idea! Puede alegrar el estado de ánimo y es una manera fácil de frenar la negatividad causada incluso por los peores errores.

Pero si no lo usas perfectamente, puede parecer condescendiente e insultante para el usuario. eso es solo un a lo grande riesgo de tomar.

Mailchimp lo dice bien:

[N]o se esfuerce por hacer una broma: el humor forzado puede ser peor que nada. Si no estás seguro, mantén una cara seria.

(El énfasis es mío)

Escribir marcado accesible

Fácilmente podríamos dedicar un artículo completo a la accesibilidad y cómo se relaciona con la redacción técnica. Diablos, la accesibilidad a menudo se incluye en las guías de estilo de contenido, incluidas las de Microsoft y MailChimp.

Eres un desarrollador y probablemente ya sepas mucho sobre accesibilidad. Incluso puede ser uno de los desarrolladores más diligentes que hace de la accesibilidad una parte central de su flujo de trabajo. Aún así, es increíble la frecuencia con la que las consideraciones de accesibilidad se dejan en un segundo plano, sin importar lo importante que todos sabemos que es hacer que las experiencias en línea sean accesibles y que incluyan todas las habilidades.

Por lo tanto, si se encuentra implementando la redacción de otra persona en su código, escribiendo documentación para otros desarrolladores o incluso escribiendo UI cópiese a sí mismo, tenga en cuenta algunas de las mejores prácticas fundamentales de accesibilidad, ya que completan todos los demás consejos para la redacción técnica.

Cosas como:

Andy Bell ofrece algunos relativamente pequeñas cosas que puede hacer para que el contenido sea más accesible, y vale la pena echarle un vistazo. Y, solo por diversión, John Rhea muestra algunos buenos trucos de edición que son posibles cuando estamos trabajando con elementos HTML semánticos.

Conclusión

Esas fueron seis formas que demuestran cómo coinciden la escritura técnica y el desarrollo. Si bien es posible que los ejemplos y los consejos no sean ciencia espacial, espero que los encuentre útiles, ya sea colaborando con otros desarrolladores, manteniendo su propio trabajo, teniendo que escribir su propia copia en un apuro o incluso redactando una propuesta de proyecto, entre otros. cosas.

El resultado final: perfeccionar sus habilidades de escritura y poner un poco de esfuerzo adicional en su escritura puede convertirlo en un mejor desarrollador.

Recursos de redacción técnica.

Si te interesa la redacción técnica:

Si estás interesado en la redacción:

Si te interesa la microcopia:

Si está interesado en utilizar una guía de estilo profesional para mejorar su escritura:

Si estás interesado en escribir sobre accesibilidad: