Cómo redactar una propuesta y un esquema para un tutorial de la comunidad de DigitalOcean

Introducción

¿Quieres escribir un tutorial para DigitalOcean? El equipo editorial de DigitalOcean está aquí para apoyar a escritores como tú: desarrolladores e ingenieros que quieren compartir sus conocimientos con otros miembros de la comunidad.

Como DigitalOcean no puede aceptar todos los tutoriales que nos envían, le pedimos que nos muestre una propuesta antes de aprobarlo para que comience a escribir. No queremos que escriba todo el tutorial antes de saber si lo aceptaron, por lo que le pedimos un esquema detallado. De esa manera, tenemos una buena idea de lo que quiere escribir y podemos ofrecerle algunos comentarios antes de que comience a escribir. Ese es el mejor momento para realizar cambios en la estructura de su artículo, porque es mucho más fácil revisar un esquema que un borrador. Con un buen esquema, tiene un marco que hace que el proceso de escritura sea más fluido.

En este artículo, verá cómo elaborar una propuesta y un esquema para su idea de tutorial. Primero, realizará algunos preparativos que lo ayudarán a dar forma al contenido, decidirá el objetivo que desea que alcancen los lectores y luego definirá los pasos que los llevarán a lograrlo. El proceso de escritura es iterativo, por lo que es posible que vuelva a los pasos anteriores, pero este marco lo ayudará a crear el esquema.

Paso 1: definir tu enfoque

Lo primero que hay que decidir es sobre qué se quiere escribir. A menudo, se empieza con un solo sustantivo, por ejemplo: Nginx, Helm o React. A continuación, hay que buscar el verbo que va con el sustantivo: ¿qué se quiere que hagan los usuarios con el producto? O, dicho de otro modo, ¿cuál es el resultado de aprendizaje para el lector? En esta etapa, hay que cambiar el foco del escritor al lector. En lugar de “¿sobre qué quiero escribir?”, la pregunta pasa a ser “¿qué quiere lograr el lector?”. Encontrar el verbo adecuado dará respuesta a esa pregunta. Los verbos como “aprender” o “entender” no son buenos temas para un tutorial, porque no tienen un resultado mensurable. En su lugar, hay que considerar verbos como estos:

• Instalar
• Crear
• Configurar
• Integrar
• Desplegar
• Monitor
• Prueba
• Seguro
• Automatizar
• Solucionar problemas

Casi todos los tutoriales de DigitalOcean comienzan con las palabras “Cómo hacer”, lo que le da una pista para elegir un buen verbo. Los siguientes son buenos títulos de tutoriales que utilizan los sustantivos con los verbos adecuados:

• Cómo configurar Nginx como servidor web y proxy inverso

• Cómo instalar software en clústeres de Kubernetes con el administrador de paquetes Helm 3

• Cómo gestionar el estado con ganchos en componentes React

Esto le permite establecer claramente el objetivo de aprendizaje para el lector, lo que también debería ayudarlo a definir el título. Ambos son datos que le solicitaremos en su propuesta.

Una vez que tengas el tema definido correctamente, puedes centrar tu atención en a quién estás escribiendo.

Paso 2: Decidir la audiencia

El siguiente aspecto que hay que tener en cuenta al planificar un tutorial es quién lo va a leer. ¿Quién se beneficiará más con el tutorial y cuánto saben ya? Cuánto saben ya determinará cuánta información de fondo hay que proporcionar, lo que afecta a la extensión del tutorial.

Por ejemplo, el tutorial Configuración inicial del servidor con Ubuntu 20.04 presupone muy pocos conocimientos previos. Explica qué es el root y cómo funcionan las claves SSH. Este es un tutorial adecuado para lectores que configuran un servidor por primera vez.

El tutorial Cómo entregar versiones de forma progresiva con Flagger en DigitalOcean Kubernetes supone que el lector tiene mucha más experiencia. Se supone que los lectores están familiarizados con Kubernetes, Helm y Nginx, y que ya tienen un clúster configurado para usar todas estas tecnologías. Esto permite al autor omitir la configuración de esos productos y concentrarse en Flagger, que es el tema del tutorial.

Nota: Los tutoriales de requisitos previos son útiles cuando el tutorial propuesto es avanzado. DigitalOcean tiene una biblioteca de más de 3000 tutoriales, cualquiera de los cuales se puede usar como requisito previo para el tutorial que estás proponiendo. El tutorial de Flagger tiene requisitos previos para configurar Kubernetes, Helm y Nginx, entre otros.

En el caso de los tutoriales de DigitalOcean, suele ser mejor tener un público específico que uno amplio. Si escribe sobre cómo configurar los ajustes de equilibrio de carga de Kubernetes, puede pensar que el público objetivo debería incluir a todos los que usan Kubernetes, pero tendrá un tutorial más útil si enfoca el público objetivo solo a los administradores de Kubernetes que tienen suficientes clústeres y tráfico como para requerir un ajuste fino de los equilibradores de carga. En otras palabras, un público más avanzado.

Eso no significa que tu tutorial no tenga un gran atractivo y que puedas brindar un contexto adicional para atraer a lectores con otros niveles de habilidad. Sin embargo, las etapas de planificación serán más fáciles si mantienes a la audiencia acotada.

Definir tu audiencia te dará una idea de cuánto contenido necesitas cubrir, o en otras palabras, el alcance.

Paso 3: Decidir el alcance

Al igual que con la audiencia, el alcance de un tutorial de DigitalOcean debe ser limitado. Intente concentrarse en una sola tarea. Un tutorial sobre “Cómo implementar una aplicación Node con un frontend React y un almacén de datos MySQL” tiene muchos componentes y muchos pasos. Preferiríamos ver un tutorial sobre cómo implementar una aplicación Node . Una vez que se publique con éxito el primer tutorial, puede proponer otro utilizando el primer tutorial como requisito previo y desarrollar una solución más compleja de esa manera.

También es preferible un alcance limitado porque queremos que los lectores puedan reproducir los pasos correctamente. Podrías escribir un tutorial sobre monitoreo que involucre seis servidores diferentes, pero el lector tendría que configurar esa cantidad de Droplets, lo que podría resultar inconveniente o costoso. Si puedes lograr el mismo objetivo con solo dos Droplets, los lectores pueden extrapolarlo a una red más grande.

De manera similar, trate de evitar tutoriales que requieran múltiples tecnologías diferentes. Un tutorial sobre (por ejemplo) “Cómo implementar una aplicación Flask con TravisCI y monitoreo de Grafana con Nginx en Debian”, solo sería útil para los lectores que usen todas esas tecnologías exactas. Eso limita la vida útil del tutorial, si una de esas tecnologías se reemplaza o ya no se admite. La excepción a esta guía son los tutoriales que están específicamente destinados a demostrar el uso de una pila de tecnología específica, como LAMP o Elastic.

Con los límites del tutorial definidos, puedes comenzar a crear el marco para tu tutorial con un esquema.

Paso 4: Lluvia de ideas sobre las tareas

Ahora que ya sabes sobre qué quieres escribir y para quién, puedes empezar a elaborar un esquema. La primera parte de ese proceso es hacer una lluvia de ideas sobre lo que implica el problema que estás intentando resolver. Piensa en la tarea general que implica y en los procesos individuales que podrías llevar a cabo. Por ejemplo, si estuvieras escribiendo un tutorial sobre Cómo instalar Nginx en Ubuntu , incluirías un paso para sudo apt install nginx, pero también hay otras consideraciones. En este tutorial, el autor ha incluido estos pasos adicionales:

• Ajuste del firewall para permitir el acceso

• Verificando el servidor web

• Gestión del proceso

• Configuración de bloques de servidor

Esos pasos no son estrictamente parte del install nginxproceso, pero son necesarios para una instalación adecuada de Nginx, por lo que un tutorial agrega valor a la documentación básica. Piense en el proceso para identificar estas tareas adicionales y anótelas a medida que se le ocurran. No es necesario que las tenga en orden en este momento; solo está definiendo el contenido que se va a cubrir.

Esto puede llevar algo de tiempo. Por ejemplo, es posible que no pienses en ajustar el firewall de inmediato, porque normalmente lo tienes configurado correctamente. Cuando lo pienses, escríbelo. Sé inclusivo en este paso. Piensa en tareas que podrían ser “agradables de tener” o que no estén estrictamente relacionadas. Una vez que hayas pensado en todo lo que te gustaría incluir, es hora de organizarte.

Paso 5: Organizar las tareas en un esquema

El paso anterior le proporcionó una lista de posibles tareas para incluir en el tutorial, por lo que la siguiente parte es organizarlas. Algunas de ellas serán claras, debido al flujo de operaciones: debe ejecutar el install nginxcomando antes de poder probar los resultados, por lo que el paso de instalación debe realizarse primero. Algunos pasos pueden no ser tan obvios: ¿deberían los lectores configurar el firewall después de la instalación o antes? Piense en cada paso en términos del objetivo de aprendizaje para el lector: ¿cómo lo ayuda este paso a avanzar hacia el objetivo general? Algunos pasos no tendrán un lugar específico donde deban realizarse, y eso está bien.

Asegúrese de que cada paso del proceso logre algo tangible, es decir, que cada paso tenga un verbo útil. Si escribió “Entender cómo funcionan los firewalls” como un paso, eso no logra nada demostrable. El paso “Configurar el firewall” deja al lector con algo concreto: un firewall que bloquea la mayor parte del tráfico, pero admite parte del mismo.

Es posible que hayas anotado algunos pasos que están fuera del alcance del tutorial. Por ejemplo, necesitas un servidor Ubuntu antes de poder instalar Nginx en él, pero eso se trata en otro tutorial, por lo que no necesitas un paso aparte para ello. En este caso, puedes agregar “configurar el servidor Ubuntu 20.04” a la lista de requisitos previos, junto con un enlace al tutorial existente. Nuevamente, recuerda el objetivo de aprendizaje que definiste en el Paso 1 y deja que eso te sirva de guía para determinar si los pasos están dentro del alcance o no.

Es posible que otros pasos sean demasiado avanzados para incluirlos en este artículo. Es posible que desee instalar Nginx para usarlo como proxy inverso, pero esa configuración es independiente de la instalación y es mejor tratarla en un tutorial aparte. En nuestro tutorial de ejemplo, el autor recomienda configurar bloques de servidor, pero advierte que es una recomendación, no una parte obligatoria de la instalación.

Finalice su esquema agregando algunos detalles sobre cada paso. Cuéntenos en pocas palabras exactamente qué hará el lector, por qué cada paso es importante y cómo se relaciona con el siguiente. Para el paso del firewall, podría agregar “Los lectores usarán el perfil HTTP Nginx de ufw para permitir solo el tráfico en el puerto 80. Esta es una configuración estándar para un servidor web público”.

Paso 6: Cómo evitar las trampas en el contorno

El esquema cumple dos funciones: sirve como marco que facilitará el proceso de escritura y permitirá que el equipo editorial de DigitalOcean sepa sobre qué planea escribir, para que puedan decidir si lo aceptan para su publicación. A continuación, se indican algunas cosas que solemos ver en los esquemas y que recomendamos evitar para tener más posibilidades de que lo acepten:

• Pasos de contexto: si tiene un paso en el que el lector no hace nada concreto, o un paso que solo proporciona contexto, busque otro lugar para colocar esa información. Si desea proporcionar algunos antecedentes sobre para qué se usa comúnmente una tecnología, puede hacerlo en la sección Introducción del tutorial. Si está explicando por qué los lectores están dando un paso, considere usar una explicación “justo a tiempo”. Por ejemplo, en lugar de explicar primero la teoría detrás de los firewalls, haga que el lector use los comandos para configurar el firewall y luego explique exactamente por qué usó esos comandos específicos. Los lectores aprenden mejor cuando tienen algo práctico que vincular con la teoría.

• Pasos sin explicación: los editores de DigitalOcean tienen mucha experiencia con diversas tecnologías, pero no somos expertos en todo. Agregar una explicación a cada paso de su esquema nos ayudará a entender cómo se combinan los pasos para lograr su objetivo. Un paso como “Configurar un usuario” puede no ser claro por sí solo, pero podría agregar “El servicio de base de datos requiere un usuario dedicado con permisos específicos, por motivos de seguridad. En este paso, los lectores crearán ese usuario y establecerán los permisos”. De esa manera, sabremos por qué es necesario este paso.

• Clonación de un repositorio: muchos esquemas tienen un Paso 1 que pide a los lectores que clonen un repositorio para obtener un proyecto de muestra para implementar en el tutorial. Evitamos este patrón por varias razones. En primer lugar, debemos asegurarnos de que el repositorio esté disponible durante la vida útil del tutorial. (Si se necesita un repositorio, lo clonaremos en el sitio de la Comunidad de DigitalOcean y lo alojaremos aquí). En segundo lugar, no pedimos a los lectores que ejecuten código que no hemos explicado completamente, por razones de seguridad. En tercer lugar, tratamos cada bloque de código como una oportunidad de aprendizaje, incluso si no está directamente relacionado con el tema del tutorial. Si su proyecto incluye un archivo CSS que es demasiado complejo para explicar sin distraer del tutorial, considere simplificar el CSS. Mantener el proyecto de muestra al mínimo necesario para el tutorial le permite mantener el enfoque donde corresponde.

• Pasos demasiado largos: A veces, tendrá un paso que incluya otras tareas subordinadas. Por ejemplo, puede tener un paso que requiera serializar información en el servidor, transmitirla al cliente y luego deserializarla antes de renderizarla. Si descubre que su paso se beneficiaría con subtítulos, es una señal de que debe dividir el paso en dos o más pasos más pequeños. Su editor puede ayudarlo a asesorarlo sobre este tema.

Conclusión

En este tutorial, has realizado los pasos previos a la redacción necesarios para definir tu tutorial y darle un enfoque. Has refinado la idea, identificado la audiencia y el alcance, has pensado en los pasos necesarios y has finalizado el esquema. Esto te proporciona una base sólida desde la que comenzar a escribir y también proporciona la información que nuestros editores necesitan para decidir si aceptan tu tutorial para su publicación. Es normal que los esquemas cambien durante el proceso de redacción, ya sea por sugerencias de tu editor o por lo que descubres mientras escribes. No pienses en el esquema como algo inmutable, sino más bien como un marco que te permite mantenerte en el buen camino.

Para obtener más información y orientación sobre el proceso de redacción, contamos con una variedad de recursos que pueden ayudarlo. Consulte nuestras Pautas de redacción técnica , Recomendaciones técnicas y mejores prácticas y Plantillas de tutoriales .