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.

imagen

驴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.

imagen

  • 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:

imagen

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.

imagen

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: 鈥淧ara cambiar al modo de pantalla completa:鈥 (鈥淧ara 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:鈥 (鈥淧ara 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:

imagen

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:
imagen

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:
imagen

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.

imagen

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.

imagen

Continuar谩 ...

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

Source: https://habr.com/ru/post/442224/


All Articles