Mal consejo: ¿cómo escribir documentación técnica? Parte dos

Consejos para escribir de manera competente documentación técnica para los usuarios.
Parte 2

Continuación del manual de nuestro escritor técnico Andrei Starovoitov, que ayudará a que su documentación de usuario sea más fácil y comprensible.

Puede leer el comienzo del artículo aquí , pero describimos el proceso de documentación y localización de nuestros productos anteriormente en este artículo .

En esta parte, analizaremos en detalle los temas que comprenden principalmente la documentación del usuario (especialmente la Guía del usuario), a saber, los temas de tareas , que describen cómo resolver un problema específico.



¿Cuántas tareas describir en el tema, una o más?

Un tema de tarea puede describir tanto una tarea: "Iniciar una aplicación de Windows" ("Iniciar una aplicación de Windows"), como varias tareas relacionadas. Por ejemplo, el tema "Optimizar rendimiento" puede consistir en las siguientes secciones: "Ahorrar automáticamente espacio en disco" y "Ajustar su MacBook para un mejor rendimiento o ahorrar batería" ("Optimizar su MacBook para una mayor duración de la batería o un mayor rendimiento ").

Deberíamos tratar de escribir temas de tareas sobre el principio: un tema - una tarea. Es cierto, hay una excepción: si tiene dos tareas que son opuestas en acción, entonces deben describirse en un tema. Por ejemplo, si necesita describir cómo cambiar la máquina virtual al modo de pantalla completa y cómo salir más tarde, debe hacerlo dentro del mismo tema.
Si necesita describir varias tareas relacionadas, esto también se puede hacer en un tema, siempre que su descripción no sea larga.

Secciones de temas de tareas

Los temas de las tareas consisten en:

• Rumbo
• Parte introductoria (en inglés "intro")
• Frases, lo que lleva a una descripción de lo que el usuario debe hacer exactamente (en inglés "encabezado de paso")
• Numerados o comenzando en pasos de un punto grande (en inglés "pasos numerados o con viñetas")
• La parte final (en inglés "outro")

A veces sucede que el tema de la tarea no contiene todas las secciones anteriores; por ejemplo, no es necesario insertar Intro u Outro. Además, nos detendremos en más detalles sobre cada sección del tema.

Titular

Debemos tratar de hacer tales encabezados para que el usuario entienda de inmediato lo que se escribirá en el tema.

Haga titulares espaciosos, pero no demasiado largos al mismo tiempo. Es posible que los encabezados largos no se muestren completamente en algunos navegadores o en el Visor de ayuda de Apple.

Al escribir un titular, use el imperativo ("Hacer esto")

Por ejemplo, "Configurar una impresora con Bonjour".

No utilice el imperativo en los nombres de temas que no describen cómo resolver un problema.

Use palabras fáciles de usar en el nombre del tema, no se concentre en los elementos de la interfaz.

El usuario no quiere comprender las características, los términos, los elementos de la interfaz, etc., necesita resolver su problema específico. Por lo tanto, en nombre del tema, intente usar las palabras que usaría el propio usuario. Por ejemplo, si llama al tema "Configure su Mac para usar aplicaciones de Windows", será mucho más comprensible para el usuario que el tema "Acerca de las máquinas virtuales".

Intente formular el objetivo como probablemente lo haría el usuario. Por ejemplo, en lugar de "Iniciar una sesión remota", mejor nombre al tema "Comenzar a controlar Windows de forma remota".

Si necesita utilizar términos técnicamente complejos o nombres de interfaz, lo mejor es hacerlo no en el encabezado, sino en la introducción del tema.

Si está escribiendo documentación en inglés, las palabras en el título deben comenzar con una letra mayúscula

Derecha : configure su Mac para usar aplicaciones de Windows

Incorrecto : configure su Mac para usar aplicaciones de Windows

(Discutiremos la capitalización del encabezado con más detalle en la siguiente parte del manual)

Introducción (Introducción)

En la parte introductoria, que va inmediatamente después del encabezado, debe escribir lo que el usuario necesita saber antes de comenzar a realizar la tarea.

El prólogo puede contener:

• Información general adicional: lo que el usuario puede hacer.
• Motivación : por qué el usuario puede necesitar realizar una u otra acción. Aquí hay una parte introductoria de ejemplo que describe por qué podría necesitar descargar y usar máquinas virtuales listas para usar:

Use máquinas virtuales listas para usar

Si no tiene tiempo para crear una nueva máquina virtual con la configuración necesaria, puede descargar la máquina virtual terminada con una configuración preconfigurada.

• Advertencias sobre cualquier posible daño al hardware, software o pérdida de datos que pueda ocurrir mientras el usuario realiza una acción.
• Información importante sobre posibles problemas o dificultades que, aunque no provoquen daños a la salud, el equipo o la pérdida de datos, pueden ocurrir durante la ejecución de una tarea.
• Explicación: qué significa este o aquel término o cómo funciona alguna característica.

Por ejemplo, si un usuario de Parallels Desktop desea trabajar con macOS y Windows al mismo tiempo, como si se tratara de un sistema operativo, en la parte introductoria puede hablar sobre el "Modo de coherencia" para preparar al usuario para términos que se utilizará más en el tema.

• Información sobre condiciones adicionales : por ejemplo, en el tema que describe cómo conectar la impresora a través de Bonjour, la introducción puede informarle sobre qué versiones de Windows son compatibles con Bonjour.
• Condiciones necesarias para la tarea actual : si antes de comenzar a realizar las tareas descritas en el tema, el usuario necesita hacer o verificar otra cosa, esto debe mencionarse en la parte introductoria. Y sería bueno dar enlaces a temas donde se describe para que el usuario pueda encontrar y leer rápidamente.

No inserte el prólogo donde no sea necesario.

Aunque la parte introductoria proporciona información útil adicional, a veces todo está claro en el título mismo. En tales casos, no necesita presentar un texto introductorio, si solo fuera así.

Por ejemplo:

Inicie aplicaciones Mac a través del menú Inicio

Abra el menú Inicio de Windows y realice una de las siguientes acciones:

• Haga clic en Todos los programas> Aplicaciones compartidas de Parallels y seleccione la aplicación que desee.
• Ingrese el nombre de la aplicación en el campo de búsqueda y seleccione la aplicación deseada de las opciones propuestas.

No hagas el prólogo demasiado tiempo

La introducción es demasiado larga y molesta al usuario. En tales casos, los usuarios a menudo lo omiten y van directamente a la lista de pasos específicos.

Si la parte introductoria es demasiado grande, debe mencionar la principal y dar un enlace a una página conceptual o página de referencia separada, en la que todo ya se describirá en detalle.

A veces, para facilitar visualmente la lectura de textos largos en la parte introductoria, se pueden usar viñetas. Por ejemplo:



No diga en la introducción cómo completar la tarea

El prólogo no es para esto. Qué debe hacerse, dónde y cómo: es necesario describirlo más tarde, después de la parte introductoria.

Sin embargo, en casos excepcionales, es posible que deba informar a los usuarios qué necesitan para completar la tarea. En el siguiente ejemplo, la parte introductoria le dice a los usuarios lo que necesitan para completar la tarea descrita en el tema.



No describa los resultados de la tarea en la introducción.

Esto debe hacerse en la parte final ( Outro ).

La frase antes de las instrucciones (Título del paso)

Después de la Introducción, debe insertar una frase "introductoria" (en inglés - "encabezado de paso"), que lleva al usuario a instrucciones: qué debe hacerse exactamente para lograr uno u otro resultado.

Por ejemplo, en Introducción, escribimos: “ Si tiene un disco de instalación y una clave de activación, puede usarlos para instalar Windows en una máquina virtual. "

Después de la Introducción viene el encabezado del paso: " Para instalar Windows: "

Y luego los pasos mismos:

1) Haz clic aquí.
2) Elige esto.
3) Y así sucesivamente ...

Tenga en cuenta: si no hay introducción en el tema, el encabezado del paso es opcional.

Si el tema describe pasos secuenciales, entonces el encabezado del paso debería verse como " Para hacer algo:" ("Para hacer X:").
Por ejemplo: “Para cambiar al modo de pantalla completa:” (“Para iniciar Windows:”) o “ Para cambiar al modo de pantalla completa:” .

No olvides poner dos puntos al final

Si el encabezado usa palabras fáciles de usar y tiene que usar términos técnicos complejos o los nombres de los elementos de la interfaz en las instrucciones, puede hacer lo siguiente: en la parte introductoria explica el significado del término, y en el encabezado del paso ya lo usa activamente.

Por ejemplo:

1) hacemos el encabezado más claro para el usuario:

" Configurar Windows para ocupar toda la pantalla"

2) A continuación, en Introducción, presentamos el término "Modo de pantalla completa".

3) Después de esto, en el encabezado del paso ya puede usar el término sin temor a que no sea comprensible para el usuario:

“ Para ingresar a pantalla completa:” (“Para ingresar a pantalla completa:”)

Si los pasos descritos en el tema no son una secuencia de acciones, sino varias formas de lograr el objetivo, entonces el encabezado del paso se debe hacer de la siguiente manera: "Aquí hay algunas formas de hacer algo:" ("Aquí hay formas de hacer X:") o " Para hacer esto, realice una de las siguientes acciones: " (" Para hacer X, realice una de las siguientes acciones: ").

Por ejemplo, "Aquí hay formas de cerrar Windows:") o " Para conectar una impresora, realice una de las siguientes acciones: " ("Para conectar una impresora, realice una de las siguientes acciones: ").

Al crear el encabezado del paso, debe usar las palabras que reflejan la tarea descrita en el tema de la tarea. Aquí hay algunos ejemplos en inglés:

Título de la página : Instale Windows desde un disco de instalación.
Tareas : instalación de Windows utilizando un disco de instalación.
Encabezado del paso : para instalar Windows.

Título de la página : ajuste la configuración de coherencia.
Cubiertas de tareas : personalización de cómo Windows aparece y se comporta en modo Coherence.
Encabezado de paso: para personalizar el modo Coherence.

Título de la página : Configure Windows para que ocupe toda la pantalla
Cubiertas de tareas : Entrar en modo de pantalla completa.
Encabezado de paso : para ingresar al modo de pantalla completa, realice una de las siguientes acciones:

Pasos numerados

Todos los temas que describen cómo realizar una tarea en particular contienen instrucciones sobre qué hacer. Estas acciones en el texto generalmente están numeradas (si es una serie de pasos consecutivos) o resaltadas con viñetas (si se propone elegir una de la lista a su discreción).

Mantenga la lista de pasos necesarios lo más breve posible.

Elija y describa la forma más fácil y rápida de completar una acción. Se pueden describir métodos alternativos en la parte final (Outro) o en otro tema de la tarea. No obligue al usuario a leer las instrucciones en 4 pasos, si puede hacer lo mismo haciendo clic en un botón.

Si la forma más fácil es realizar la acción a través de la barra de herramientas, describa esta opción. Si la barra de herramientas se puede personalizar a su gusto y tiene dudas, de repente la configuración de la barra de herramientas del usuario difiere de la descrita en el tema, describa todo como se hace con la configuración predeterminada. Como muestra la práctica, la mayoría de los usuarios comunes rara vez cambian la configuración de "fábrica".

Si necesita describir varias formas de realizar una acción en un tema :

Si en muchos temas de tareas de su libro se repite cierta acción que se puede realizar de diferentes maneras (por ejemplo, a través de un menú o barra de herramientas), seleccione un método y mencione secuencialmente en cada tema de tarea.

Si hay una forma alternativa simple y corta, y sin duda desea hablar sobre ello, puede hacerlo en el mismo paso.

Por ejemplo: "Para abrir la configuración de la máquina virtual, elija Acciones> Configurar o haga clic en el icono Configurar en la esquina superior derecha").

Numere los pasos a realizar secuencialmente.

Para no inflar la descripción y no resaltar instrucciones muy breves en pasos separados (como "Hacer clic en Aceptar"), puede combinar 2 acciones relacionadas y relacionadas en un solo paso, como se muestra a continuación:



Use viñetas para resaltar acciones inconsistentes

A veces, al usuario se le ofrecen varias formas de elegir cómo lograr el objetivo. En tales casos, las opciones propuestas emiten viñetas.

Por ejemplo:


Si la lista contiene los nombres de elementos gráficos, resáltelos para mayor claridad en negrita

Si la acción que debe realizar el usuario enumera una serie de elementos de la interfaz gráfica (elementos de menú, daws, etc.), inicie cada opción desde una nueva línea, resaltando el nombre del elemento en negrita. Después del elemento marcado en negrita, ponga dos puntos y luego explique la descripción en texto plano.

Como se muestra en este ejemplo:


Si el texto en el tema hace referencia a varios elementos de la interfaz muchas veces, puede valer la pena crear un tema de ayuda por separado en el que se describirán estos elementos.

Esto será especialmente útil si muchos temas en la guía se refieren a los mismos elementos. En este caso, al comienzo del tema, debe dar un enlace al tema de referencia en el que se explica el elemento mencionado.

Si este elemento se menciona nuevamente más adelante en el texto, ya no necesita darle un enlace, solo uno al principio. Cuando hay muchos enlaces en el tema, esto puede complicar la percepción y la comprensión de lo escrito.

La parte final (Outro)

Outro es la información final que viene después de los pasos numerados. Intente acortar la parte final: no use más de 3 párrafos, cada uno de los cuales consta de un máximo de 3 oraciones.

Use Outro para describir los resultados o consecuencias de estas acciones.

Un ejemplo de un resultado o consecuencias puede ser:

• Información sobre dónde se instalaron los archivos;

• Aparece un mensaje que requerirá acciones adicionales del usuario;

• Configuración que el usuario deberá cambiar después de que se hayan completado las acciones descritas.

Por ejemplo, la parte final del tema sobre cómo hacer que Parallels Access funcione solo en Wi-Fi, dice lo siguiente: “ Si configuró Parallels Access para funcionar solo en Wi-Fi y no se detectan redes inalámbricas, aparece un mensaje preguntándole - ¿Te gustaría conectarte a través de 3G? ".

En la parte final del tema, puede describir una forma alternativa de completar la tarea.

Si el método alternativo puede describirse en una oración, puede hacerlo en la parte final del tema.

Outro puede proporcionar más información relacionada con la tarea actual.

Dicha información puede informar a los usuarios de qué más pueden hacer después de completar la tarea descrita.

En el siguiente ejemplo, el tema describe cómo encontrar un archivo desde una máquina virtual en macOS Finder. Y en la parte final del tema se describe qué más puede hacer el usuario con el archivo después de encontrarlo.



En Outro, puede describir información adicional que solo necesitan algunos usuarios.

Por ejemplo, en la parte final del tema sobre la integración de máquinas virtuales de Windows en macOS, puede escribir lo siguiente: "Si tiene una MacBook Pro 2016 o posterior, puede trabajar con algunas aplicaciones de Windows utilizando la barra táctil"


Divide las tareas largas en etapas cortas

Básicamente, los temas de las tareas son cortos y caben en una página. Sin embargo, si se describe una tarea compleja y muy larga, que se puede dividir en etapas, etapas y procedimientos, vale la pena separar lógicamente la información y describir cada etapa en un tema separado para que la descripción parezca más simple, mejor leída y comprendida.

El siguiente es un ejemplo del contenido de la Guía del usuario de Parallels Desktop. La captura de pantalla muestra un capítulo que describe varias formas de instalar Windows en una máquina virtual. Y una de las formas, cómo importar datos desde una computadora remota, se divide en varios temas.



Continuará ...

(en la siguiente parte hablaremos más sobre temas conceptuales y de referencia y temas que ayudan a resolver problemas)