Escribir entradas de blog técnicas sobre proyectos de codificación

Se podría decir que escribir código es más fácil que escribir sobre código. El código básicamente funciona o no funciona, mientras que el lenguaje natural puede fallar o tener éxito de todas las maneras posibles. Pero si eres un gran programador, tienes la mayoría de las habilidades que necesitas para tener éxito en ese otro tipo de escritura, y otros desarrolladores pueden beneficiarse de que compartas tus ideas.

Escribir una entrada de blog es similar a escribir código:

• Desarrollas una idea y esbozas cómo llegarás de la nada a su plena realización.

• Sigue las reglas sintácticas para evitar malas interpretaciones.

• Usted se esfuerza por ser lo suficientemente prolijo como para que se le entienda, pero simplificando siempre que sea posible.

Cuando escribes sobre hay otras técnicas que puedes utilizar. Pero también ayuda centrarse en lo que el lector quiere de la entrada. Una ventaja de los artículos técnicos sobre otros tipos de escritos es que lo que quiere el lector suele ser bastante obvio.

Redacción técnica eficaz

El problema es que la escritura técnica es árida. Cada persona tiene sus propias estrategias para mitigarlo, pero los trucos ingeniosos no pueden cambiar ese hecho fundamental. Leer explicaciones abstractas de algoritmos y sintaxis es una tarea difícil. El cerebroespecialmente la memoria-y la información técnica ofrece pocos puntos de apoyo para esas asociaciones.

Esto no sólo se aplica a la escritura técnica. Si alguna vez has tenido dificultades para mantenerte despierto durante una charla de media hora o una conferencia, pero no tienes problemas para concentrarte en una película de dos horas, ya lo sabes. El aburrimiento tiene menos que ver con las personas que reciben la información que con la forma en que se presenta.

¿Por qué la gente lee entradas de blogs técnicos? En general, quieren saber cómo realizar una tarea o profundizar en un tema concreto. Tu reto es responder a esa necesidad antes de que se agote su capacidad de atención.

Lo único que casi siempre mejora la escritura técnica es su menor extensión. Esto se aplica tanto a la longitud del artículo como a la de las frases. Incluso en los ejemplos de código. Consumir información técnica ya es un reto suficiente para nuestros cerebros. Puedes ayudar a la gente a entender tu tema haciendo el trabajo de priorizar la información para ellos y eliminando todo lo que no sea crucial.

Hay muchos enfoques diferentes que puedes utilizar para aligerar la escritura que te queda. Algunas herramientas eficaces son:

• Humor

• Antropomorfización de conceptos o código

• Imágenes (GIFs, no gráficos circulares)

• Ejemplos interactivos

• Código

• Listas con viñetas

Algunas de esas técnicas afectan a la propia escritura y otras permiten descansar de ella. Pero todas ellas utilizan partes del cerebro distintas de la que recuerda fórmulas y algoritmos. Los recuerdos están hechos de enlaces entre partes del cerebro, y recordar las cosas que vas leyendo a medida que avanzas es clave para evitar el agotamiento mental el tiempo suficiente para comprender el panorama general.

Si no has hecho mucha redacción técnica, o no has hecho mucha con la que te hayas sentido satisfecho, puede que merezca la pena experimentar con otras formas de aligerarla. La voz auténtica del autor es tan importante en una entrada de blog sobre código como en cualquier otra parte. Tu voz se amplifica con una estrategia bien planificada que resulte natural.

Términos técnicos

Por supuesto, está bien hablar de hacer chistes y añadir GIFs para animar tu escritura, pero en algún momento, vas a tener que sumergirte en las turbias aguas de los acrónimos y la notación húngara.

La primera forma de manejar la terminología técnica es dar marcha atrás y asegurarse de que has delimitado correctamente el alcance de tu entrada. Una entrada de blog en la que tengas que dedicar varios párrafos a explicar cada término técnico probablemente no debería ser la misma en la que utilizas varios términos técnicos en una misma frase. Si te encuentras mezclando muchos términos técnicos y crees que nadie los conoce todos, puedes enlazar el término con su definición canónica en lugar de explicarlo en exceso. También puedes dividir tu entrada en dos, con una precuela opcional que cubra todo el trabajo preliminar que algunas personas quieran saltarse.

Para que tu redacción sea menos árida, incorpora términos técnicos al flujo narrativo de tu post. Así, en lugar de:

"getData es el nombre de la función que obtiene los datos. Su valor de retorno es output. Puede no devolver nada o devolver un objeto. Recibe dos argumentos. source es el primer argumento, y filter es el segundo, que es opcional".

Podrías integrar términos técnicos con lenguaje natural de esta manera:

"Al pasar un dato source a getData como primer argumento, podemos obtener un objeto output objeto que contiene nuestros datos. Opcionalmente podemos añadir un filter para reducir los datos devueltos. Si no hay coincidencias getData devolverá simplemente null."

Puede resultar tentador tratar los términos técnicos con una especie de formalidad, pero creo que hace que la escritura sea mucho más difícil de digerir. La forma en que le hablarías a alguien con quien estás programando en parejas sobre el código en el que estáis trabajando juntos será inmediatamente más clara.

El papel del formato

Cambiar entre nombres narrativos y variables sin ser explícito sobre lo que estás haciendo es posible gracias a las etiquetas <code> en el HTML final de la entrada. Dan una indicación visual de que estás hablando de un elemento específico de la solución técnica, y también pueden ser reconocidas por las tecnologías de asistencia. Cualquier otro formato de los términos técnicos, como poner en negrita el nombre de una determinada tecnología o herramienta, depende de ti o de la guía de estilo de tu organización.

La forma de formatear los bloques de código también es importante. Como mínimo, resulta útil resaltar la sintaxis. Esto no sólo hace que el código sea más fácil de entender visualmente, sino que también proporciona interés visual dentro de tu entrada. El código en los bloques de código debe estar limpio para tu post. Si los comentarios del código explican lo mismo que la entrada del blog, puedes eliminarlos para presentar menos código. También puedes eliminar la sangría heredada del código para que no sea necesario desplazarse horizontalmente para leerlo.

Formatear tu entrada en subsecciones es útil para organizar la información y, dependiendo de la plataforma de blog que utilices, puede proporcionar atajos de navegación dentro de la entrada. También puedes utilizar apartados y listas con viñetas para organizar la entrada. Eso sí, no te pases con el formato. La mayoría de las entradas de blog deberían ser en su mayor parte texto, aunque traten sobre código.

Enlazar con otros recursos merece un poco de estrategia. Si has encontrado algo útil y encaja de forma natural en el flujo de tu texto para enlazarlo, tener la información extra en contexto es útil. Pero no conviene añadir tantos enlaces en el texto que distraiga. Si tienes muchas cosas a las que enlazar, siempre puedes poner una lista al principio o al final de la entrada. Eso también tiene una ventaja, y es que no anima a la gente a dejar de leer e irse a otro sitio a mitad del tutorial.

Uso de imágenes

El uso de imágenes es bastante habitual en artículos de noticias y otros contenidos que pueden pasar por un proceso de producción más largo que una entrada de blog. También es habitual tener al menos una imagen principal en los artículos técnicos. Ya hemos hablado del valor de esto.

Las entradas de blogs técnicos también pueden utilizar imágenes en el cuerpo de la entrada. Pueden ser más visuales, como GIFs para romper el texto, o explicativas. Las únicas consideraciones que hay que tener en cuenta con las imágenes decorativas son de tipo legal y de accesibilidad. Si se autoriza el uso de la imagen y se subtitula con cuidado, no habrá problema.

Algunos Conceptos técnicos se benefician de una demostración visual. Puedes hacer una captura de pantalla de los pasos de un proceso de configuración o convertir el proceso en un GIF. También puede ser útil mostrar estructuras de directorios, ejemplos de salida o una interfaz de usuario que no estés codificando en el post. Sin embargo, es importante no depender completamente de las imágenes para estas cosas. Debes seguir explicando lo que hay en la imagen o dar suficiente información para que la gente pueda producir lo mismo localmente.

Explicar el código

Si vas a escribir una entrada de blog sobre un fragmento de código, debes planificar la explicación del código. Apuntar a tus lectores a un repositorio, narrar unas pocas líneas y dejar caer tu cuenta de Twitter es poco probable que resulte en una entrada de blog muy útil.

Si el código de la entrada de tu blog está escrito específicamente para ese propósito (no es una parte de un proyecto más amplio), es muy útil llevar un registro de los pasos que das para crearlo a medida que lo vas codificando. De este modo, dispondrás de un esquema listo para la entrada. Incluso puedes tomar notas literalmente de tus pasos en la entrada del blog y una vez que el código esté hecho, voilàtu esquema ya está listo. Si el código es sólo una parte de algo más, averigua qué partes son cruciales para el objetivo de tu entrada y organízalas de forma que las primeras partes que discutas sean las dependencias de las siguientes.

Se trata de sugerencias genéricas, por supuesto. Si estás diseccionando el código de otra persona, o simplemente explicando algo realmente complejo, empezar con el producto final y adoptar un enfoque de "cómo lo hicieron" puede ser genial.

Un truco que creo que funciona bien es escribir la narrativa alrededor de tu código como si los ejemplos de código no estuvieran ahí. Otra forma de pensar en esto es como si estuvieras dando una entrevista de codificación y necesitaras expresar las partes importantes de la solución dejando los detalles de implementación sin especificar. Es probable que la gente busque algo en una entrada de blog que no puede obtener simplemente mirando el repositorio de GitHub, por lo que una entrada de blog debe hacer algo más que decir: "Ahora vamos a añadir la función:". getData Hay un punto intermedio entre eso y repetir todo el bloque de código en lenguaje natural.

La forma de dividir el código puede ayudar a encontrar el equilibrio adecuado entre explicación y autodocumentación. Si puedes dividir tu código en bloques con unas diez líneas importantes (cosas que no sean repeticiones o paréntesis de cierre), puedes escribir un párrafo de 2-3 frases explicando cada una y mantener un buen ritmo. Pero no siempre es posible. Algunas funciones son enormes.

Si el código que necesita discutir es muy largo, considere la posibilidad de dividirlo artificialmente. Yo prefiero hacerlo dejando comentarios como //INSTANTIATE VARIABLES y //FETCH VALUESpara no tener que cambiar el funcionamiento del código e introducir un error en el último momento. Sin embargo, dividir el código largo en módulos o funciones separadas también funciona. Añadir abstracciones hace que tu código sea mucho más fácil de discutir, y el mismo beneficio de reutilización que obtienes en el propio código es el que pueden compartir tus entradas de blog. Si vuelves a escribir sobre un tema similar, puedes reutilizar esas piezas e incluso su explicación.

Para terminar

Al final de la entrada, es útil confirmar cuál es el resultado esperado. Si tu lector ha ido codificando a lo largo de cada paso y obtiene errores, probablemente ya sospeche que ha habido un malentendido. Pero no siempre es así. Podrías concluir diciendo: "Ahora ya tienes listo el código de tu aplicación. Sólo tienes que configurar tus credenciales API siguiendo este tutorial y podrás ejecutar la aplicación".

Si llegas al final de la entrada y no tienes mucho más que decir, es un buen indicio de que has definido correctamente el alcance de la entrada. Si incluyes muchas advertencias en párrafos adicionales, considera la posibilidad de volver atrás y arreglar las cosas del código o del artículo que te están molestando.

La parte final de la redacción de una entrada de blog técnica es la misma que la de una no técnica: editarla. Con una entrada de blog técnica, es importante comprobar manualmente cualquier sugerencia procedente de una herramienta de corrección automática. Si tienes que editar bloques de código, asegúrate de que el código sigue funcionando.

Si estás interesado en escribir un artículo técnico en tu blog sobre tu trabajo con las API de Vonage, actualmente estamos aceptando propuestas para nuestros programa Developer Spotlight para desarrolladores.