Como escribir un buen tutorial.

Antes que me lluevan críticas y comentarios, este tutorial lo escribo para el uso de los autores de este blog. Si a más personas le sirve pues bienvenido sea. Aunque no es tema de este blog aprender hacer tutoriales, la idea de enseñar como hacer uno tiene como objetivo que las personas que deseen aportar sus conocimientos lo hagan correctamente. Nuestro blog siempre está abierto a colaboraciones de los temas que tratamos.

Hacer un tutorial puede parecer simple. Pues tú sabes que dominas el tema y crees que con saberlo debería bastar. Pero puedes encontrarte ante la imposibilidad de trasmitir tus conocimientos. Un tutorial se debe escribir para un lector con escasos conocimientos y, por lo tanto, responde a una dinámica de escritura muy pormenorizada, que debe seguir una estructura lineal, clara y concisa. Empezaremos por definir:

¿Qué es un tutorial?
Un tutorial es una serie de instrucciones conectadas, una guía paso a paso, que busca enseñar una, y solo una, tarea. Debe tener todo lo necesario para que el objetivo se pueda completar con éxito y el usuario llegue al final con una solución a su problema, inquietud o necesidad.

Es importante destacar que un tutorial no es un manual. Un manual enseña el uso general de algo, no una acción específica dentro del mismo. Por ejemplo, Guía a los usuarios para armar una fuente lineal, no enseña electrónica en general. Resumiendo: los manuales o cursos son una serie de tutoriales conectados que pasean al usuario por todos los aspectos de un programa u oficio, para que aprenda mediante la práctica. La experiencia nos dice 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.

Preproduccion o Perfila tu idea

Paso 1: ¿Hace falta?

Hazte la siguiente pregunta: ¿es realmente necesario, va a ser de utilidad, va a aportar algo?. Si el tutorial que te planteas escribir ya está bien explicado en otro lugar qué sentido tiene que lo repitas tu. A menos que aporte algo nuevo, actualice o aclare el que ya está escrito. Muchas veces simplemente hacemos traducciones de otros tutoriales y los enriquecemos con nuestra experiencia. Siempre que se haga esto debemos mencionar la fuente en que nos basamos. También se da el caso de que un tema no está bien explicado, ni claro en varios tutoriales y se hace un recopilación de todos y se transforma en un texto más entendible.

Paso 2: Planeamiento

En este paso una vez que ya sepas que tema vas a tratar, necesitas plantearte cual es la mejor forma de hacerlo. Aquí es donde planeas la estructura de tu tutorial. Debes tener bien clara el tipo de audiencia al cual vas a dedicarle tu tutorial.

Paso 3: Herramientas y/o condiciones para la creación del tutorial

Antes de comenzar a escribir, asegúrate de tener todas las herramientas que necesitas. Si llevas capturas de pantalla o imágenes tenerlas todas listas y etiquetadas. Si tienes un borrador donde tengas una idea de cómo estructurar el tutorial, te servirá de mucho. Si debes interrumpir la redacción a cada rato, probablemente demores el triple. Por lo que es mejor tenerlo ya todo listo.

Comenzar a crear el tutorial

Paso 1: Título y descripción

El título y la descripción deben ser lo suficientemente claros para que el lector determine si desea o no seguir leyendo. Por lo tanto, debe ser muy claro y cuidadoso a la hora de ponerle un título a su tutorial. El mismo debe abarcar el tema que se quiere tratar, y a la vez ser conciso. Se debe hacer siempre una breve introducción del tema a tratar donde se intentará enganchar al lector. Es importante destacar que un tutorial es una guía que carece de valor literario. Por lo tanto, no es algo se disfrute al leer. Por más didáctico que sea, por más ameno que lo hagas, no deja de ser una utilidad, la descripción de una tarea paso a paso.

Paso 2: Observaciones

Es importante que antes de comenzar el tutorial en sí, escribas las observaciones que creas convenientes. Las observaciones dependen muchísimo sobre lo que escribas. Pueden ser simples consejos, una explicación de los métodos y programas que usarás, enlaces de descargas de programas que se van a utilizar durante el paso a paso, una lista de los “ingredientes” necesarios o una advertencia de los posibles problemas con los que se puede encontrar el lector, entre otras cosas. En resumen, las condiciones iniciales que necesitaras para poder llevar a cabo el tutorial. Por ejemplo:

Para este tutorial necesitaras un VM de 2 núcleos con 4 GB RAM y 8GB de HDD

Paso 3: Paso a paso

Todos los tutoriales deben seguir un paso a paso claro y conciso. Sin palabras de más que distraigan la atención del lector. Si tus lectores son novatos pues los pasos serían más largos porque tendrías que explicar el porqué de cada uno. No dejes nada a la comprensión del lector. La ambigüedad es tu enemiga número uno.

Paso 4: Haz, luego escribe
Debes entender que el lector, si está usando un tutorial, es porque no sabe. Así de simple y crudo. Cosas que para ti son obvias, puede que para el lector no. Lo ideal, entonces, es escribir a medida que vas haciendo la tarea que explicas. Así, podrás documentar el paso a paso, sacar capturas, fotos o capturar vídeos. También evitarás la omisión de pasos y te asegurarás que el proceso funciona.

Paso 5: Numeración
Aunque pueda parecer irrelevante, la numeración sirve para la comprensión y la estructuración del tutorial. Te obliga a ti a seguir un orden y al lector a leer sin saltearse nada. Además, numerando puedes hacer referencia a puntos anteriores (por ej,: “Cómo vimos en el paso 5”) o evitar al usuario leer pasos irrelevantes, en caso que cumpla alguna condición (por ej.: “Si ya tienes instalado el códec, pasa al Paso 12”).

Paso 6: Imágenes, capturas.
Como te contamos en el paso 4, debes sacar imágenes del proceso. La escritura tiene sus límites, más cuando queremos mantener las cosas simples. Hay procesos que son complicadísimos de escribir, pero que con mostrar una imagen quedan ilustrados a la perfección. Tú te ahorras trabajo y los lectores esfuerzo y frustración. Idealmente, cada uno de los pasos debería contar con una imagen de ejemplo, salvo que sean redundantes. Las imágenes, si son complejas, deben tener marcadas las partes a las que debe prestar atención.

Paso 7: Usa ejemplos
Si crees que algún concepto es difícil de entender, usa ejemplos al alcance de todos. Los ejemplos, claro, no siempre pueden resolverse de manera tan simple. Si estamos hablando de cosas más complejas, serán necesarios ejemplos más complejos.

Paso 8: Céntrate en un tema
Nunca intentes enseñar más de una cosa por tutorial. Si para realizar un tutorial con éxito, el usuario necesita realizar tareas previas, que también requieran conocimiento y práctica, es que necesitas hacer dos (o más) tutoriales.

Paso 9: Relee, rehace y reescribe
Te sorprenderá ver la cantidad de errores que tendrá tu tutorial cuando lo termines. Sea porque lo escribiste apurado, por pequeñas incongruencias gramaticales o porque sí, la mayoría de las veces nunca es perfecto en la primera escritura.
Y siempre deja un canal de comunicación abierto para las dudas. Realiméntate de los comentarios que dejen, así sabrás si usaste un lenguaje entendible para los novatos en el tema que trataste.

Ahora pasaremos a mostrarles cómo usar las herramientas (plug ins) que posee este blog para ayudarte a escribir un tutorial. Empezaremos con:

  • Syntax highlighter

El resaltado de sintaxis, a veces llamado coloreado de sintaxis, es una capacidad para tratamiento de textos, para diferenciar elementos de texto (especialmente en código fuente) mediante diversos colores o estilos tipográficos, dependiendo de las categorías sintácticas de sus términos, conforme a las reglas de algún lenguaje formal concreto. Este resaltado se utiliza a modo de notación secundaria, habitualmente para mejorar la legibilidad del código fuente de programas o de textos escritos en algún lenguaje de marcado, permitiendo aumentar la productividad de los programadores.

Como se usa:

En el editor de WordPress elegiremos pegar código usando la herramienta Syntax highlighter como se aprecia en la figura.

Nos abrirá una ventana nueva donde pegaremos el código y configuraremos a nuestro gusto

  1. Ponerle un título que describa para qué es el código que estamos pegando (esto es opcional)
  2. Elegir el tipo de lenguaje del código que estamos pegando.
  3. Área donde insertaremos el código, respetando su sintaxis original.
  4. Tema que usaremos para mostrar el código en el tutorial.
  5. Tipo de letra con el cual será mostrado.
  6. Por último le damos añadir el código al tutorial

Un ejemplo de cómo luce seria así:

Simple Lightbox

Es una aplicación hecha en JavaScript, que consiste en:

Al hacer clic en una imagen, que ésta se amplíe en una ventana nueva (ventana lightbox) con la siguiente estructura: la imagen aparece ampliada en el centro, mientras el resto de la pantalla queda transparente. Además, ofrece la opción de agregar títulos a la imagen o la de crear una galería (de imágenes que se encuentran en la misma página) con flechas para ir pasando de una a otra.

Para lograr que este efecto funcione debemos subir la imagen a nuestro WordPress pero activando siempre la casilla de enlazado a archivos de medio.

  1. Imagen a adjuntar.
  2. Opcion OBLIGATORIA de enlazado a archivo de medios.
  3. Insertar la imagen.

Si olvidamos marcar esa opción en el momento de adjuntar la imagen no importa porque podemos editarla después y configurarla. Seleccionamos la imagen y nos mostrara un menú emergente y elegimos editar

Nos abrirá otra ventana de detalles de la foto donde enlazaremos nuestra imagen al archivo correspondiente. Luego le damos al botón de actualizar.

El resultado final luce así. Con solo dar clic en cualquier imagen del tutorial nos abrirá la imagen en primer plano más grande y mejor resolución.

  1. Reanudar o detener la presentación de imágenes (slideshow).
  2. Flechas para moverse entre las fotos del tutorial.
  3. Cantidad de imágenes en ese tutorial.

Glosario

Muchas veces usamos un término y le asociamos un enlace para que el lector se remita a leer en otra web, pero es mucho más cómodo si en el mismo tutorial se aclarase. ¿Como logramos esto sin complicar al lector? Pues muy fácil usaremos la herramienta de GLOSARIO. Lo primero que debemos hacer es crear el termino en el glosario del blog. Para los autores del blog se les mostrara un menú a su izquierda de la pantalla donde podrán elegir Termino de Glosario.

Una vez abierto crearemos la definición del término, presionando el botón añadir nuevo termino.

  1. Nombre del término (es el nombre exacto que usaremos para llamarlo)
  2. Definicion del término. La misma no debe ser muy extensa, solo definir de forma concisa el término.
  3. Crear el término.

Como se usa:

Una vez creado, se usa de la siguiente forma. Cuando está escribiendo el tutorial y desea agregar el término se hace de la siguiente manera:

NOTA: Se hace en la vista VISUAL NO en la vista HTML.

El resultado luciría así:

Con solo posicionar el puntero encima del término y esperar, nos cargara la definición del mismo en una forma elegante. Sin tener que truncar la lectura del tutorial. Si desea ver todos los términos de glosario usados en el blog están en el menú principal del blog.

Creación de Índice o Menú de salto (enlaces ancla)

Qué hacer cuando creamos un tutorial muy extenso que abarca varias partes y queremos que el lector no se pierda al buscar información en él. Pues, usamos un índice el cual ubicamos al principio de cada parte del tutorial, asi podremos navegar entre las diferentes partes. ¿Como logramos esto? Pues muy sencillo usaremos enlaces ancla.

La primera forma para crear enlaces ancla en WordPress es simplemente hacerlo manualmente con HTML en cada una de las publicaciones. Creemos una para que pueda ver cómo funcionan.

Usando el típico botón de crear enlace se puede crear un hipervínculo a otra web, pero en lugar de enlazarlo a su URL, publicación o página; usted lo asignará a un nombre ancla. Las URLs que designan anclas contienen un carácter “#” seguido por el nombre del ancla. Puede nombrarlo como usted quiera, aunque normalmente recomendamos mantenerlo corto y relacionado al nombre real del encabezado.

Si usted observa esta vista del texto (HTML) lucirá así:

otra forma seria:

En esta forma la referencia es un enlace a la propia página o una externa, pero al final se usa el carácter # seguido de un ID. En este caso 1 porque es el primer tópico del índice. Resumiendo:

Luego, usted necesita agregar una ID en el encabezado adonde quiere que su enlace salte. Para hacer esto, necesitará cambiar a la vista del texto (HTML) en el editor de WordPress. En el encabezado, en este caso, un encabezado H2, agregue la ID junto con el nombre del ancla que eligió en el anterior. El nombre del ancla y la ID del atributo tienen que ser exactamente los mismos para que el enlace funcione. tomando como referencia los ejemplos anteriores.

o

Una de las formas más sencillas para agregar enlaces ancla es con el plugin gratuito TinyMCE Advanced. El plugin básicamente agrega funcionalidades extra al editor con botones de atajo. Después de haber instalado y activado el plugin, vaya a su publicación y cree un hipervínculo en su texto ancla. En lugar de enlazarlo a una URL, publicación o página; usted lo asignará a un nombre ancla precedido con un #.

Resalte el encabezado al que quiere enlazar. Luego de clic en “Insertar” desde el botón en la parte superior y seleccione “Texto de enlace.” Este botón aparece en el editor gracias al plugin de TinyMCE Advanced.

MENU1

Ahora al dar clic sobre el link que dice Salto al menú 1 no llevara a MENU1 (nótese que tiene un símbolo de ancla delante)

Para terminar enumero otra serie de buenas prácticas para aumentar el SEO del blog.

  1. No olvidar nunca darle categoría a su tutorial para que sea facil de catalogar.
  2. Crear etiquetas de contenido para su publicación así será fácil de encontrar.
  3. Etiquetar las imágenes con texto alternativo.
  4. Establecer una Imagen destacada acorde con el tema del tutorial. La misma debería tener de dimensiones 256 por 256 píxeles.
  5. Revisar errores de ortografía y redacción
  6. Siempre nombrar las fuentes de consulta
  7. Guardar siempre como borrador nunca publicar sin estar seguros. Debe esperar ser revisado por un editor del blog.

Como TIP final les diré la forma en que reviso de automáticamente la ortografía. Una vez terminado de escribir todo el texto me paso a la pestaña de HTML en el editor de WordPress. Selecciono todo el texto del tutorial y lo pego en una hoja vacía de Word. Reviso la ortografía minuciosamente y la redacción. Cuando termino copio todo el contenido revisado y lo pego en mi editor de WordPress borrando previamente lo que estaba. Recuerde que esto siempre se hará en la pestaña de HTML para respetar el formato.

Para la realización de este tutorial se usó varias fuentes de internet y la experiencia de este servidor. Espero les sirva a los que se aventuren a cooperar con nosotros.

¿De cuánta utilidad te ha parecido este contenido?

¡Haz clic en una estrella para puntuar!

Promedio de puntuación 4.9 / 5. Recuento de votos: 10

Hasta ahora, ¡no hay votos!. Sé el primero en puntuar este contenido.

Sobre Alexander Rivas Alpizar 61 artículos
Administrador de Redes EMPRESTUR Cienfuegos

Sé el primero en comentar

Dejar una contestacion

Tu dirección de correo electrónico no será publicada.


*