Consejos para escribir de manera competente documentación técnica para los usuarios.
Parte 1
En un artículo anterior, describimos cómo se lleva a cabo el proceso de
documentación y localización de nuestros productos .
Esta vez, debajo del corte, está el manual de
nuestro escritor técnico Andrei Starovoitov, que ayudará a que su documentación sea más fácil y comprensible para los usuarios (Apple, Microsoft y otras compañías utilizan las técnicas descritas para documentar sus productos).
Como saben, una buena documentación no es un lujo, sino un medio para aumentar las ventas de la compañía. Si va a comenzar o ya está desarrollando algún tipo de programa, para ingresar al mercado mundial con él, necesitará un manual del usuario (también conocido como Guía del usuario) o al menos un documento que le diga a los clientes cómo comenzar a trabajar con su producto (el llamado Comenzando con).
Usted decide en qué idioma escribir la documentación, en ruso y luego traducirla, o inmediatamente en inglés. En Parallels, elegimos el segundo enfoque. A menudo es mucho más fácil hacer una descripción en inglés, ya que casi todos (y ahora podemos decir que "todos") los términos de computadora en ruso son prestados.
Más adelante en el texto, nos centraremos en los ejemplos en ruso e inglés.
Entonces, ¿qué debe buscar al escribir documentación?
Tipos de temas en la documentación.
Al escribir un tema, primero debe determinar qué tipo de tema será :)
De esto dependerá de qué y cómo escribir en él.
Hay
4 tipos principales de temas :
•
Temas que describen cómo resolver una tarea específica o varias tareas relacionadas (en inglés, este tipo de tema se denomina
páginas de tareas) .
Por ejemplo, "Instalar Parallels Desktop" o "Apagar o Pausar Windows". Cada uno de estos temas describe una serie de uno o más pasos que un usuario debe tomar para lograr un objetivo específico. El manual del usuario consta principalmente de dichos temas.
Por lo general, a los usuarios no les gusta leer, especialmente cuando hay mucho texto. Por lo tanto, debe intentar que dichos temas sean lo más cortos posible. Idealmente, si la información se presenta de la siguiente forma: "puede hacer algo, simplemente haga clic aquí y aquí" (los temas de las tareas se discutirán con más detalle en la siguiente parte del artículo).
Si el desarrollador cree que hay información adicional que el usuario necesita saber, y hay mucha, entonces esto se describe mejor en temas conceptuales (ver más abajo).
•
Temas conceptuales (en inglés -
páginas de conceptos ). En estos temas no hay instrucciones sobre cómo resolver ningún problema. Contienen información que más bien contribuye a una mayor comprensión de las cosas. Por ejemplo, los temas conceptuales se utilizan para:
- Explicar a los usuarios exactamente cómo funciona cualquier proceso;
- decir qué se puede hacer en la configuración de la aplicación;
- describa las características agregadas en la nueva versión del producto;
- Proporcionar información adicional que ayudará al usuario a comprender o resolver mejor un problema.
Tenga en cuenta que se debe proporcionar información adicional (en caso de que haya mucha) de manera precisa en el tema conceptual para no sobrecargar el tema de la tarea.
•
Temas de ayuda (en inglés:
páginas de referencia ): contienen información que el usuario puede consultar periódicamente para averiguar qué significa un término en particular, cómo funciona una función, etc. Un buen ejemplo de estos temas es el diccionario al final de la guía (también conocido como Glosario). Los temas de referencia son especialmente útiles para explicar el propósito de varios elementos de la interfaz.
•
Temas que describen cómo resolver un problema (en inglés:
páginas de solución de problemas ).
Por ejemplo: "No puedo activar Parallels Desktop" o "No puedo conectarme a Internet". Estos temas describen lo que hay que hacer para resolver un problema. También pueden contener información que ayudará a comprender cuál es la causa del mal funcionamiento.
Instrucciones básicas para todo tipo de documentación.
Al crear una guía:
1)
Concéntrate en el usuario
• En lugar de estructurar la descripción del producto en función de sus características o elementos de interfaz, intente concentrarse en las tareas que es más probable que el usuario intente resolver.
Por ejemplo, un tema sobre cómo proteger los datos en una máquina virtual se puede llamar de 2 maneras:
a) "Configuración de seguridad", que describe en detalle lo que se puede hacer para proteger los datos.
b) Haga varios temas que describan tareas específicas:
- "Proteja sus datos con software antivirus"
- "Copia de seguridad de su máquina virtual" ("Copia de seguridad de su máquina virtual")
De acuerdo con las tendencias actuales en la documentación, el segundo enfoque es preferible, ya que en este caso el usuario no tiene que adivinar si debe hacer algo o no, y recibe instrucciones claras sobre lo que debe hacerse exactamente.
• Centrarse en las tareas del usuario y su nivel de conocimientos técnicos.
Por ejemplo, en la documentación para el usuario promedio, en lugar de escribir "Crear una máquina virtual", debe escribir "Instalar Windows o cualquier otro sistema operativo", como el término " máquina virtual "está lejos de ser conocida por todos. U otro ejemplo: un tema que describe cómo crear atajos de teclado rápidos, es mejor llamar a "Configurar atajos de teclado" en lugar de "Configuración de teclado".
Aunque lo importante es que para la mayoría de los lectores de Habr sería más claro "Configurar accesos directos", pero la pregunta ya es cuánto dicho término es apropiado en la terminología oficial en este momento :)
• Si esto puede no estar claro, explique por qué el usuario puede necesitar realizar una tarea en particular.
Por ejemplo:
• Al describir, intente usar esas palabras que el usuario usa todos los días en su discurso. Si un término técnicamente complejo puede ser reemplazado por palabras más simples, siempre trate de usar palabras más simples.
Por ejemplo, "transparente" en lugar de "transparente". Si da un ejemplo del idioma inglés, use "use" en lugar de "utilize".
2)
Intenta dar toda la información necesaria sin palabras innecesarias“Los embajadores de la isla de Samos vinieron a Esparta para pedir ayuda. Hicieron un discurso largo y hermoso. Los espartanos dijeron: "Habiendo escuchado el final, olvidamos el principio, y olvidando el principio, no entendimos el final". Los Samosets eran ingeniosos. Al día siguiente, llegaron a la reunión con una bolsa vacía y dijeron solo cuatro palabras: "Hay una bolsa, no hay harina". Los espartanos los regañaron: dos palabras fueron suficientes: "no hay harina", pero estaban satisfechos con su ingenio tan rápido y prometieron ayudar ".Si describe la funcionalidad demasiado tiempo, nadie la leerá. Pero también es completamente "en espartano", porque si se escribe muy poco habrá preguntas y dudas, los usuarios comenzarán a atraer al equipo de soporte. En general, es importante mantener el equilibrio.
Para ayudar a los usuarios a encontrar toda la información que necesitan y al mismo tiempo describir cada sección lo más brevemente posible:
- Concéntrese en la información más importante que se necesita para resolver el problema descrito en el tema. Si algunos detalles no son necesarios para la tarea, no los describa.
- No es necesario documentar cada clic. Si todo está claro en la interfaz, deje que el usuario lo descubra por sí mismo. Por ejemplo, en lugar de documentar cada paso de la instalación del programa, es mejor escribir: "Para instalar el programa, siga las instrucciones en pantalla". Si, como la última etapa de un procedimiento, debe hacer clic en Aceptar, tampoco vale la pena describirlo.
- En lugar de proporcionar toda la información en un tema, muéstrele al usuario dónde puede leer información adicional utilizando enlaces a otros temas, enlaces a recursos externos, o inserte al final la sección "Información relacionada", que contendrá enlaces a temas relacionados con lo que se describe en la pantalla.
- Si una tarea larga puede dividirse en varias etapas o subtareas, cada una de las cuales es una tarea separada, divida el tema en las secciones apropiadas o cree una sección en la guía, que consista en temas que describan cada etapa. En este caso, no olvide insertar enlaces a temas relacionados.
- Si una tarea (por ejemplo, iniciar una máquina virtual) se puede realizar de varias maneras, no es necesario describirlas todas. Baste mencionar la forma más rápida y fácil. Si aún cree que es útil para el usuario conocer cualquier otro método, descríbalo al final (en inglés - Outro) tema.
3)
No repita la misma información en las páginas.
En lugar de repetir información en cada tema que ya se describió en algún otro tema, es mejor hacer referencia a que se puede encontrar una descripción más detallada en ese tema, o simplemente darle un hipervínculo.
4)
Atrae la atención del usuario correctamente
Cuando la descripción necesita atraer la atención del usuario, se utilizan las siguientes palabras introductorias: "¡Atención!" (en inglés - ¡Advertencia!), "Importante:" (en inglés - Importante :) y "Nota:" (en inglés - Nota :).
Cada una de estas palabras implica su propio nivel de "importancia".
Para no forzar al usuario en vano, use cada término correctamente:
- ¡Atención! (¡Advertencia! En inglés) para indicar una situación peligrosa que, si no se evita, podría provocar la pérdida de datos, daños en los componentes o cualquier otro daño.
- Use "Importante:" (en inglés - Importante :) para indicar una situación significativa y potencialmente problemática que, sin embargo, no puede provocar daños físicos, daños o pérdida de datos.
- Utilice "Nota:" (Nota :) para proporcionar información adicional relacionada con este tema. Aunque tal inserción separa a los usuarios de la tarea actual, puede ser útil.
Por ejemplo:
Para abrir la configuración de la máquina virtual, haga clic en Acciones> Configurar.
Nota: La máquina virtual debe estar apagada.
Use la nota "Nota:" con moderación: si la inserta con demasiada frecuencia, obstruye el texto y deja de prestarle atención.
Si es posible, inserte "¡Atención!", "Importante:" y "Nota:" al comienzo del tema para que el usuario se entere de esto antes de comenzar a realizar cualquier procedimiento. Sin embargo, si la información solo se refiere a un paso en particular, insértelo después de este paso.
Un ejemplo:
Continuará ...(en la siguiente parte del artículo discutiremos con más detalle temas que describen cómo resolver un problema específico)