Redacción Técnica para Desarrolladores | trucos CSS

HTML, CSS, JavaScript, Python, PHP, C++, Dart: hay tantos lenguajes de programación, ¡y es posible que incluso domines algunos de ellos! Pero a medida que nos esforzamos por escribir más y mejor código, la forma en que escribes y te comunicas en el lenguaje cotidiano se vuelve cada vez más importante... y tal vez incluso se pasa por alto.

La forma en que escribimos para y alrededor del código es quizás tan importante como el propio código. E independientemente 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 eficiencia del código.

En este artículo, quiero describir cómo estos dos campos aparentemente diferentes, la programación y la 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 un libro de texto con sugerencias de escritura, consejos y ejemplos de 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 pasan entre 3 y 6 horas al día escribiendo código.

Y sí, esta es una encuesta que cubre un grupo bastante específico, pero me imagino que muchos de nosotros caemos en algún lugar de ese rango. En cualquier caso, un programador no escribe código las 24 horas del día, los 7 días de la semana porque, como muestra este estudio, dedicamos mucho tiempo a otras cosas.

Esto puede incluir:

• demostrar una nueva característica,
• documentando esta nueva característica,
• actualizar un ticket de trabajo relacionado con esta nueva característica, o
• trabajo pendiente para admitir esta nueva función.

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

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

Así que pasamos mucho de nuestro tiempo comunicándonos con la gente. 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 deletreáramos mejor nuestras palabras, nos comunicaríamos mejor. Cuando nos comunicamos mejor, es más probable que consigamos lo que queremos.

Esta es la escritura técnica 101.

Y ni siquiera termina ahí... A algunos desarrolladores también les gusta hacer sus propios productos, lo que significa que tienen que hacer que el marketing sea parte de su trabajo. La escritura técnica también juega un papel muy importante en esto. Entonces sí. Creo que es bastante justo decir que la escritura técnica es Por supuesto En todas partes.

¿Qué es una buena gramática?

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

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 una breve descripción del lenguaje.

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 idioma inglés y se dividen en ocho cubos:

Piense en estos como interfaz de usuario componentes: son partes modulares que puedes mover para construir una oración completa y sólida, de la misma manera que podrías armar un todo y una oración interfaz de usuario. ¿Todos los componentes tienen que estar allí todo el tiempo? ¡Ciertamente no! Arma una oración con las partes 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 idioma inglés. Los usamos para compartir ideas, comunicarnos con nuestros amigos y familiares y enviar correos electrónicos a nuestros colegas.

Pero es importante tener en cuenta sonido de nuestros mensajes. Es increíble cómo un signo de exclamación puede cambiar por completo el tono de un mensaje:

1. Me gusta programar.
2. yo me gusta ¡programación! 🙂

Es fácil confundir voz con 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 estar escrita de manera formal, seria y profesional en un esfuerzo por ir directo al grano.

Un mismo mensaje escrito con dos voces diferentes:

• entretenimiento: "Expanda su red social y manténgase informado sobre lo que está de moda ahora".
• en serio: "Encuentre un trabajo en una de las aplicaciones de redes sociales y mercado de trabajo en línea más grande".

No es raro escribir accidentalmente mensajes que parecen condescendientes, insultantes y poco profesionales. aquí es donde tono entra en juego. Lea sus mensajes en voz alta, haga que otras personas los lean por usted y experimente 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 reaccionas en una situación determinada.

Subjuntivo activo y pasivo

Una oración siempre contiene un sujeto, un verbo y un objeto. El orden en que vienen determina si la oración se escribe en voz activa o pasiva.

El actor ocupa el primer lugar en voz activaPor ejemplo: "CSS dibuja el fondo".

Las oraciones en las que se usa la voz activa son más claras que sus análogos. Son más claros, más breves y más comprensibles, perfectos para una voz más profesional que va directo al grano.

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á dibujado por CSS".

Los lectores normalmente convierten la voz pasiva en voz activa en sus cabezas, lo que resulta en más tiempo de procesamiento. Si alguna vez escuchó que escribir en voz activa es mejor, generalmente es por eso. Los escritores técnicos prefieren la voz activa la mayor parte del tiempo, con muy pocas excepciones, como citar investigaciones: "Se supone que...".

Pero eso no significa que siempre debas apuntar a una voz activa. Las transiciones de uno a otro, incluso dentro del mismo párrafo, pueden hacer que su contenido fluya sin problemas de una oración a la siguiente si se usa de manera efectiva.

Evitar errores

La gramática tiene que ver con la estructura y la corrección del idioma, y ​​no hay nada mejor para lograr esto que una revisión rápida de su documento.Es muy importante eliminar errores ortográficos, problemas gramaticales e imperfecciones semánticas en su redacción.

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

Pero si está buscando una herramienta gramatical única para todos, Gramaticalmente es una de las herramientas más utilizadas. No me sobornan por esto 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.

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.

Curiosamente, cada lenguaje de programación viene con un conjunto estándar de funciones para escribir un comentario. Deberían explicar qué hace 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 la pregunta que debe hacerse.

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 dejar el código como está. Lo que hace que estos ejemplos sean "perezosos" es que simplemente repiten lo que obviamente hace el código. En este caso, los comentarios son redundantes porque nos dicen que, que ya sabemos, ¡no agregan valor!

Los comentarios obsoletos no son raros en proyectos grandes; me atrevo a decir que están en la mayoría 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. No hay 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é esa historia y todo lo que viste fue el código de arriba. ¡Naturalmente, pensaría que después de ejecutar esta segunda línea de código, las "ciudades" se ordenarían de la Z a la A! Todo este fiasco confuso es causado por un comentario desactualizado.

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

Esta es una regla simple que le ahorrará a usted y a su equipo muchas tareas técnicas.

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

algunas veces, naturalmente la forma de hacer las cosas no es correcta Los programadores pueden tener que "romper" un poco los estándares, pero cuando lo hacen, es recomendable que dejen un pequeño comentario explicando su razonamiento:

 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, ¿no? Si usted fuera responsable de revisar este código, es posible que haya tenido la tentación de corregirlo sin que ese comentario explique lo que estaba sucediendo.

Otra cosa útil que puede hacer con los comentarios es reconocer 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.

Entonces, acaba de encontrar una solución a su problema en StackOverflow. Después de copiar y pegar este código, a veces es una buena idea guardar un enlace a la respuesta que lo ayudó para que pueda volver a consultarla para futuras referencias.

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

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

Escribir solicitudes de extracción

Solicitudes de descarga (relaciones públicass) son un aspecto fundamental de cualquier proyecto. Son la base de las revisiones de código. Y las revisiones de código pueden convertirse rápidamente en un lastre para el rendimiento de su equipo sin una buena redacción.

Una buena relaciones públicas la descripción resume Qué se hace un cambio y por qué Los proyectos grandes tienen una plantilla de solicitud de extracción como esta adaptada de un verdadero ejemplo:

## 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 relaciones públicas títulos

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

• Arreglar la construcción.
• Error de corrección.
• Agrega un parche.

Ni siquiera estos experiencia para describir qué compilación, error o parche estamos tratando. Un poco de detalle adicional sobre qué parte de la compilación se solucionó, qué error se eliminó o qué parche se agregó puede ayudar mucho a establecer una mejor comunicación y cooperación con tus colegas Alinea y pone a las personas en la misma página.

relaciones públicas los títulos se escriben tradicionalmente tiempo imperativoSon un resumen de una línea de todo el relaciones públicasy deben describir Qué se lleva a cabo por relaciones públicas.

Aquí hay algunos buenos ejemplos:

• Soporte para atributos 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 relaciones públicascon

Grande relaciones públicas significa una descripción enorme y nadie quiere pasar por cientos o miles de líneas de código, ¡a veces solo para rechazar todo!

En cambio, podrías:

• comunicarse con su equipo a través de Problemas,
• hacer un plan
• dividir el problema en partes más pequeñas, o
• trabaja en cada pieza por separado con la tuya relaciones públicas.

¿No es mucho más limpio ahora?

Proporcione detalles en relaciones públicas cuerpo

A diferencia de relaciones públicas título, el cuerpo es en espacio para todos los detalles, incluyendo:

• Por que es relaciones públicas ¿está hecho?
• ¿Por qué es este el mejor enfoque?
• Cualquier defecto en el enfoque e ideas para solucionarlo si es posible.
• El número de error o ticket, resultados de referencia, etc.

Informe de errores

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

Para proyectos técnicos, todas estas cosas se hacen a través de informes de problemas. Un problema bien escrito es fácil de encontrar y responder para otro desarrollador.

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

 <!-- 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

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

Si esta es una captura de pantalla de un CLI programa, asegúrese de que el texto sea claro. si esto es un interfaz de usuario 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 este es el caso, intente grabar GIF con 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á activo en su computadora. Es por eso que un buen compromiso debe incluir 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 detectó el error, así que tal vez pueda sugerir algunas posibles razones por las que está ahí. Tal vez el error solo ocurra después de encontrar un evento determinado, o tal vez solo ocurra en un dispositivo móvil.

Tampoco está de más profundizar en el código base y tal vez identificar qué está causando el problema. Entonces su problema se cerrará mucho más rápido y es probable que se le asigne el relacionado relaciones públicas.

Comunicación con los clientes

Puede trabajar como autónomo en solitario, o tal vez sea un desarrollador líder en un equipo pequeño. 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 este 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:

• ¿Quién es tu público objetivo?
• ¿Cual es el proposito de este 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, especialmente en situaciones en las que no está de acuerdo con los comentarios o la decisión del cliente. Hacer preguntas obliga a esa persona a defender sus propias afirmaciones, en lugar de atacarla defendiendo su propia posición:

• ¿Está de acuerdo con eso, incluso si tiene un costo de eficiencia adicional?
• ¿Mover el componente nos ayuda a alcanzar mejor nuestro objetivo?
• Genial, ¿quién es responsable de mantener esto después del lanzamiento?
• ¿Sabes directamente si el contraste entre estos dos colores pasa los estándares WCAG AA?

Las preguntas son mucho más inocentes y fomentan la curiosidad sobre la hostilidad.

Véndete a ti mismo

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

• Quién eres tú
• qué haces
• ¿Por qué eres adecuado para el trabajo?
• Enlaces a trabajos relevantes que ha realizado

Y una vez que obtienes el trabajo y tienes que escribir un contrato, no recuerda, no hay contenido más intimidante que un montón de jerga legal. Aunque escrito para proyectos de diseño, Sicario 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 al desarrollador con el que creen que disfrutarán trabajando que al que es técnicamente más competente o con más experiencia para el trabajo.

Microcopia de escritura

microcopia es el arte de escribir fácil de usar interfaz de usuario Apuesto a que hubo momentos en los que usted, como desarrollador, tuvo que escribir mensajes de error porque se dejaron en segundo plano hasta el lanzamiento.

Esta 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 quiere que se enfrenten sus usuarios. Pero suceden y no podemos hacer nada 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 raro ver términos inusuales escritos en un mensaje de error, como API o "tiempo de espera de ejecución".

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 o por qué ciertas cosas no funcionan. Por lo tanto, el error.

Por lo tanto, un buen mensaje de error no debe explicar por qué algo sale mal porque tales explicaciones pueden 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. Abro mi navegador, visito su sitio web e ingreso mis datos. Luego 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 es bueno culpar al usuario. Intente cambiar su mensaje a algo menos específico, como este ejemplo adaptado de los datos de inicio de sesión de Mailchimp: “Lo sentimos, esta combinación de correo electrónico y contraseña es incorrecta. 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 cuando se microcopian, crean una sensación de hostilidad hacia el usuario.

No sobrecargar al usuario

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

Pero si no lo usas Perfectoesto puede parecer condescendiente e insultante para el usuario. Es solamente un grande riesgo de tomar.

Mailchimp lo dice bien:

[D]no se moleste en bromear, el humor violento puede ser peor que nada. Si no estás seguro, mantén una cara seria.

(énfasis 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 programador y probablemente ya sepas mucho sobre accesibilidad. Incluso podría ser uno de los desarrolladores más diligentes que hacen de la accesibilidad una parte central de su flujo de trabajo. Aún así, es sorprendente 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 e inclusivas para todas las capacidades.

Entonces, si se encuentra implementando la redacción de otra persona en su código, escriba documentación para otros desarrolladores o incluso escriba interfaz de usuario cópiese a sí mismo, tenga en cuenta algunas prácticas recomendadas de accesibilidad fundamentales, ya que complementan todos los demás consejos técnicos de redacción.

Cosas como:

Andy Bell sugiere algunas cosas relativamente pequeñas que puede hacer para que el contenido sea más accesible, y vale la pena tomarse el tiempo para revisarlas. Y solo por diversión, John Rea muestra algunos ingeniosos trucos de edición que son posibles cuando se trabaja con elementos editables de HTML semántico.

Conclusión

Estas fueron seis formas que demuestran cómo la escritura técnica y el desarrollo van de la mano. Si bien los ejemplos y consejos pueden no ser ciencia espacial, espero que los haya encontrado útiles, ya sea colaborando con otros desarrolladores, manteniendo su propio trabajo, necesitando escribir su propia copia como último recurso, o incluso redactar una propuesta de proyecto, entre otras cosas.

La línea de fondo: 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 te interesa la redacción:

Si estás interesado en microcopiar:

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

Si estás interesado en escribir sobre accesibilidad: