Escribir un tutorial técnico es una buena forma de compartir tus habilidades y generar interés en tu proyecto o compañía, o promover tu lenguaje de programación favorito. No necesitas ser un programador famoso o un escritor entrenado para crear contenido técnico de calidad.
La experiencia nos enseña que cualquiera puede escribir un buen tutorial si estudia y entiende un tema específico, lo expone comprensiblemente y ha definido con claridad la audiencia a la que desea explicarlo.
A continuación te ofrecemos una serie de pasos que pueden ayudarte a cumplir este objetivo.
Tutorial técnico:
Paso 1: Perfila tu idea
Hay dos momentos importantes para validar tu idea. Primero, pregúntate cuánta información soporta un tutorial.
Puedes lograr mucho con 2 000 palabras, un centenar de líneas de código y un gráfico o dos, pero la clave es definir la aplicación de ejemplo o la temática, centrarte en ella para incluir solo información relevante, y determinar para tu exposición el nivel adecuado de conocimiento previo con que debe contar el lector. Ganas concisión y efectividad en tu exposición.
Algunas publicaciones ofrecen sugerencias breves. Pero escribir sobre la semántica de determinada línea o fragmento de código puede requerir una explicación más amplia. Un tema del tipo “Creando un sitio web en Django” quizás exija un despliegue de contenido más sustancial; podrías necesitar construir varios artículos en el proceso.
Segundo, toma siempre en cuenta la audiencia para tu artículo. ¿Qué necesita leer tu lector ideal? ¿Por qué accede a tu artículo? Son las preguntas que necesitas para definir tu audiencia.
Si es posible, modela el lector ideal a partir de algún conocido en tu trabajo, escuela, vecindad o círculo de amigos. Incluso, con base en información sobre tendencias o las demandas de un grupo específico que hayas conocido, por ejemplo, en un artículo de prensa.
No temas escribir para un público avanzado, aunque esto implique que tu trabajo exija un poco más a una audiencia general o menos avanzada. Artículos de nivel básico e intermedio son, por lo general, más demandados.
No simplifiques al extremo de que tu exposición sea incompleta o tenga vacíos. Intenta hallar el balance eficaz entre el nivel de contenido y la claridad con que lo desarrollas.
Paso 2: Prepara ejemplos de código
Una buena forma de escribir tutoriales es acompañar a los lectores en el proceso de construcción de un proyecto.
Aunque las aplicaciones de gestión de tareas son buenos ejemplos para demostrar códigos, extraer muestras de código de proyectos personales o de sistemas más únicos suele hacer que los tutoriales sean mejor recibidos. Sin embargo, tener una gran aplicación no es garantía para un buen tutorial, a no ser que utilices los fragmentos de código adecuados.
Ejemplos de código son la forma más precisa y concisa de explicar información técnica. En artículos, los bloques de código comunican exactamente lo que el autor pretende transmitir en la pantalla, pero no más. Por ello, puede decirse que los fragmentos de código son un elemento importante en los artículos técnicos, pero no se sustentan solos.
Siempre que sea posible, el código debe ser completo e incorporar todas las importaciones y el contexto necesarios para que el usuario copie y ejecute el código sin ningún problema.
Aunque el contexto pueda extender el fragmento de código y, en algunos casos, parecer repetitivo, es la mejor manera de asegurar que el lector acceda en cualquier momento al fragmento de código y lo emplee en sus propios emprendimientos.
La única excepción es cuando estás trabajando con proyectos utilizando frameworks como Django o .NET, o si estás desarrollando aplicaciones nativas para Android o iOS. En estos proyectos hay docenas de configuraciones u otros archivos llenos de código repetitivo. En esos casos, ofrece suficiente contexto para que el lector sepa identificar dónde utilizar el código de ejemplo, pero no copies ningún código innecesario.
En un artículo, un buen código es conciso, pero fácil de entender. Debes optimizar tu código para que sea legible. La práctica de intentar resolver una solución utilizando la menor cantidad de caracteres no tiene cabida en códigos de ejemplo, como tampoco lo tiene la verbosidad sin sentido.
Tu código debe seguir una arquitectura lógica y buenas prácticas de codificación. Excepto si estás escribiendo para un público avanzado, es mejor el código fácil de entender que uno que sea rápido en su ejecución.
Finalmente, ajusta la estructura de tu código correctamente. Así evitas que los lectores no piensen que está mal debido a advertencias en el IDE.
Paso 3: Cubre las brechas
Imagina que estás construyendo un puente para que tus lectores crucen un cauce. Tus lectores están en la orilla del conocimiento existente. Tu tarea es construir una ruta segura, sobre un estrecho de incertidumbre, hacia la orilla de un nuevo conocimiento.
No puedes simplemente colocar placas por millas y esperar que se mantengan seguras. Para cruzar grandes brechas, tienes que construir pilares adicionales que soporten toda la estructura. Códigos de ejemplo, citas, diagramas e imágenes. La concepción que tengas determina el orden y la distancia entre esas estructuras. Tu trabajo en la construcción del artículo consiste en cubrir cada brecha con explicación precisa e intuición.
Cada vez que comiences a escribir, concentra tu atención en una pequeña parte del tutorial. Con solo tus ideas, investigación y el código relevante frente a ti, escribe cada sección utilizando un enfoque sencillo y directo.
Evita enfocarte demasiado en encontrar un lenguaje elaborado o elegante; solo pon las palabras sobre la página. Será mucho más fácil mejorar tu trabajo una vez que tengas algo escrito y que luego puedas editar.
Planifica adecuadamente los momentos de escritura en función de tu ritmo. Determinar si escribes una pequeña parte del artículo, o toda una sección a la vez, quitará un poco de tensión cuando decidas hacerlo. Respeta el cronograma como harías con cualquier otra actividad. Periodos de no más de 45 minutos pueden ser suficientes.
Sugerencias finales
El libro Escritura para desarrolladores de software (Writing for Software Developers), de Philip Kiely, brinda muchos elementos que necesitas conocer para crear contenido técnico con calidad. Provee una guía paso a paso en el arte de crear artículos y tutoriales técnicos. Además, puedes encontrar entrevistas con 11 expertos de la comunidad (Scotch.io, Indie Hackers y Stack Overflow, entre otros).
[Versión al español de How to Write a Technical Tutorial]
