¿Para quién es?

Pregunta siempre primero: ¿Quién va a usar la guía y qué debe haber logrado cuando termine?

Un nuevo empleado de TI que conoce la terminal necesita una guía diferente a un profesor que nunca la haya abierto. Por lo tanto, el mismo sistema puede requerir varias guías. Determina qué sabe ya el destinatario, a qué tiene acceso y qué términos no le son conocidos.

¿Qué tipo de documento es este?

Una guía del usuario es una guía de acción: ayuda al usuario a completar una tarea específica. No es un libro de texto, un diccionario ni una explicación de por qué el sistema funciona como lo hace.

Si el usuario necesita una explicación durante el proceso, mantenla breve y colócala donde el usuario la necesite.

Las partes de la guía

Cómo escribir un paso

Las reglas se basan en estándares para manuales de usuario y documentación del usuario (IEC/IEEE 82079-1 e ISO/IEC/IEEE 26514).

• Comienza cada paso con un verbo en imperativo: “Abrir”, “Ejecutar”, “Verificar”.
• Realiza una acción por paso y una instrucción por oración. Mantén las oraciones a menos de aproximadamente 20 palabras.
• Escribe lo que el usuario debe ver cuando el paso esté terminado.
• Coloca advertencias antes del paso al que aplican, no después.
• Usa la misma palabra para lo mismo todo el tiempo. Si en un lugar dice “la terminal”, no debe decir “la consola” en otro.
• Explica un término técnico la primera vez que se utiliza.

Paso débil:

Configura el sitio web y verifica que todo funcione correctamente.
Mejor paso:

3. Verifica la configuración

Ejecuta:

sudo nginx -t

Deberías ver:

nginx: configuration file /etc/nginx/nginx.conf test is successful

Si ves algo diferente, ve a «Solución de problemas».

Comando, resultado esperado y marcadores de posición

• Coloque los comandos en un bloque de código y el resultado esperado en un bloque separado debajo.
• Use formato de código para nombres de archivo, rutas de archivos y comandos en el texto continuo, por ejemplo /etc/nginx/.
• Nunca escriba contraseñas reales, claves o direcciones internas. Utilice marcadores de posición claros: <server-ip>, <usuario>, <dominio>.
• Mantenga las líneas de código bajo aproximadamente 70 caracteres para que no se corten al imprimirse en papel.

Solución de problemas

Estructure la solución de problemas en torno a lo que ve el usuario:

Sintoma → posibles causas → investigación → solución → verificación

El método subyacente se encuentra en [[Método de depuración Nivel 1 - Depuración sistemática|Método de depuración]].

Capturas de pantalla

Utilice una captura de pantalla solo cuando ayude al usuario a reconocer un resultado correcto. Recorte la imagen, marque lo más importante con una flecha o un número y elimine información sensible. Escriba un texto alternativo que indique qué muestra la imagen.

• Windows: Tecla Windows + Mayús + S
• Mac: Cmd + Mayús + 4

![El Nginx Proxy Manager muestra el servidor de proxy con estado En línea](imagenes/proxy-en-linea.png)

Imprimir en PDF

1. Abra la guía en vista previa en VS Code o abra el archivo en GitHub.
2. Seleccione impresión. Windows: Ctrl + P. Mac: Cmd + P.
3. Seleccione «Guardar como PDF».
4. Navegue por el PDF. Verifique que ninguna línea de código, tabla o imagen quede cortada.

Obtén retroalimentación antes de entregar

Haz que un compañero lea la guía antes de decir que está terminada. Quien da la retroalimentación responde brevemente y se refiere al lugar específico en el texto:

1. Precisión: ¿Hay pasos o afirmaciones de las que dudes?
2. Destinatario y estructura: ¿Está claro para quién es la guía y qué debe estar listo primero?
3. Lenguaje y acción: ¿Cada paso tiene una sola acción y un resultado esperado? ¿Se explican los términos técnicos?
4. Seguridad: Hay algo que no debería haberse publicado?

Ofrece dos fortalezas y dos mejoras concretas. Sé amable y concreto: «Sugiero que expliques proxy en el paso 2, porque…» ayuda más que «poco claro». Más sobre cómo dar retroalimentación: NDLA ¿Cómo dar comentarios?.

Tarea 1 - Mejorar los pasos débiles

Reescribe cada paso de modo que tenga un verbo en imperativo, una acción y un resultado esperado. Divide los pasos que contengan varias acciones.

1. «Ahora debe iniciarse el contenedor y se debe comprobar que está funcionando».
2. «Cambia la configuración, recuerda probarla después y luego recárgala».
3. «Inicia sesión en el servidor con la contraseña Sommer2026! y ve a la carpeta del sitio web».

Tarea 2 - Escribe una guía breve

Elige una tarea que puedas realizar sin ayuda, por ejemplo, iniciar un contenedor o publicar un cambio en un sitio web.

1. Escribe para quién es la guía y qué deben ser capaces de hacer después.
2. Escribe tres a seis pasos con el resultado esperado.
3. Agrega al menos una línea en la sección de solución de problemas.
4. Deja que un compañero siga la guía sin que tú expliques nada. Corrígelo donde se quede atascado.

Más para leer

• NDLA: Cree instrucciones de uso e información para diferentes grupos de usuarios
• NDLA: Desarrolle material didáctico
• Språkrådet: Lenguaje claro
• Diátaxis sobre los cuatro tipos de documentación (inglés)