Mal consejo: ¿cómo escribir documentación técnica? Tercera parte y última

Consejos para escribir de manera competente documentación técnica para los usuarios.
Parte 3 (final)

La conclusió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.



Esta vez consideraremos con más detalle:

• temas conceptuales (páginas de conceptos);
• temas de referencia (páginas de referencia);
• temas que explican cómo resolver un problema (páginas de solución de problemas);
• dónde y cómo usar capturas de pantalla;
• y también dar algunos consejos para quienes escriben documentación en inglés.

Partes anteriores: nuestro enfoque de documentación y localización; consejos de documentación parte 1 y parte 2 .

Temas conceptuales (páginas conceptuales)

Dichos temas son necesarios para proporcionar a los usuarios información técnica adicional y, por lo tanto, no sobrecargar el tema de la tarea.

Tenga en cuenta que deben contener exactamente información adicional, pero no una forma de resolver el problema.

Los temas conceptuales son buenos para usar para:

• decir cómo funciona un proceso en particular;
• Describa qué nuevas características se agregaron en esta versión del producto;
• proporcionar al usuario información adicional que lo ayudará a tomar una decisión;
• Indica qué puede hacer el usuario en tu aplicación.

Por ejemplo, el tema "Acerca de las máquinas virtuales" puede describir qué es y cómo funciona. Pero este tema no debe contener instrucciones sobre cómo crear una máquina virtual; esto debe describirse en el tema de la tarea.

Por lo tanto, un usuario experimentado, mientras lee un tema de tarea, no se quejará: "¿Por qué me pintas lo que es? Ya lo sé ...". Y aquellos que no lo sepan verán un enlace a un tema conceptual y lo leerán.

Por lo general, los encabezados de temas conceptuales comienzan con:

• "Acerca de (algo)" ("Acerca de las máquinas virtuales");
• "¿Qué es ...?" ("¿Qué es una máquina virtual?");
• "¿Cómo funciona (algo)?" ("¿Cómo funciona una máquina virtual?");
• "Comprender los conceptos básicos de la máquina virtual", etc.

Aquí hay un ejemplo de un tema conceptual de la documentación en inglés:



Temas de referencia (páginas de referencia) :

Dichos temas describen diversa información de referencia a la que el usuario puede referirse si es necesario.

Buenos ejemplos de tales temas son:

• "Glosario" al final de la guía;
• un tema en el que describe qué elementos están disponibles en el menú y qué hacen, qué métodos abreviados de teclado puede usar al trabajar con el programa, qué iconos están disponibles en la barra de tareas, etc.

Aquí hay un ejemplo de un tema que describe los íconos de la GUI:



Temas que describen cómo resolver un problema (páginas de solución de problemas)


Dichos temas ayudan al usuario a superar un obstáculo o resolver un problema. Los temas de solución de problemas pueden tener los siguientes escenarios:

• El usuario tiene un problema y quiere resolverlo. Por ejemplo, "Mi dispositivo USB no funciona en una máquina virtual".
• El usuario intentó hacer algo y falló. Por ejemplo, "No puedo activar Parallels Desktop" ("No puedo activar Parallels Desktop").
• Hay alguna condición o condición que el usuario quiere cambiar. Por ejemplo, "Windows es lento" ("Windows parece lento").

Qué es y qué no es la resolución de problemas :

Si el usuario quiere hacer algo, pero no sabe cómo, esto debe describirse no en la resolución de problemas, sino en el tema de la tarea.

La resolución de problemas implica que el usuario intentó hacer algo (de acuerdo con las instrucciones del tema de la tarea), pero hubo algún problema y el usuario no sabe cómo resolverlo.

Por ejemplo, un tema que describe cómo usar una unidad externa en un sistema operativo invitado es un tema de tarea.

Y el tema que describe los posibles problemas: "Tengo problemas para conectar un disco duro", es un tema de solución de problemas. Su contenido implica que el usuario siguió las instrucciones, pero por alguna razón no tuvo éxito.

Si escribe un tema de tarea, y algún paso en las instrucciones puede causar dificultades leves, se le permite describirlo en el mismo paso o tema. Para dificultades menores, no es necesario escribir un tema de solución de problemas por separado.

Por ejemplo, al final del tema que describe cómo cambiar los métodos abreviados de teclado, puede agregar: "Algunas combinaciones de teclas no se pueden editar ni eliminar".

Temas de solución de problemas

Por lo general, los temas de solución de problemas tienen una estructura similar a los temas de tareas.

Consisten en:

• Título ("título")
• Parte introductoria ("introducción")
• Frase introductoria, después de la cual comienzan los pasos numerados o la información necesaria ("encabezado de paso")
• Información necesaria para resolver un problema ("pasos para la solución")
• La parte final ("outro")

Título (título de la página)

Es bueno cuando el encabezado del tema de solución de problemas expresa el problema en primera persona del usuario. Por ejemplo:

• “No puedo activar Parallels Desktop” (“No puedo activar Parallels Desktop”)
• "Windows es lento" ("Windows parece lento")
• Aparece el mensaje "Un mensaje dice 'No se detectaron máquinas virtuales'"

Si está escribiendo documentación en inglés, debe usar mayúsculas al estilo del título en el título (para mayúsculas, consulte los detalles al final del artículo):

Derecha: mi dispositivo USB no funciona

Incorrecto: mi dispositivo USB no funciona

Introducción (introducción)

Inmediatamente después del encabezado, proporcione a los usuarios la información que necesitan saber primero.

Por ejemplo:

• Explica la causa más probable del problema. Si puede haber muchas razones, describa todas las posibles.
• A veces puede describir en términos generales lo que debe hacerse para resolver un problema. En general, se deben dar instrucciones detalladas en pasos para la solución.

Frase introductoria (encabezado de paso)

Antes de la secuencia de pasos que debe seguir para resolver el problema, escriba una frase introductoria. No te olvides de poner dos puntos al final.

Si la solución al problema es una serie de acciones secuenciales:

En tales casos, la frase introductoria debe hacerse de acuerdo con los mismos principios que para los temas de la tarea (ver la segunda parte de los consejos), es decir, usar las mismas palabras que en la formulación de la tarea.

Por ejemplo, escribe un tema de solución de problemas en el que explica por qué el usuario no puede abrir la configuración de la máquina virtual (el elemento del menú está atenuado e inactivo):

Título: "No puedo abrir la configuración de la máquina virtual"

Introducción: "Si no puede abrir la configuración de la máquina virtual (el elemento del menú está atenuado), entonces la razón más probable es que la máquina virtual no está apagada".

Además, la frase introductoria: “Para abrir la configuración de la máquina virtual:” (en esta frase se usan las mismas palabras que en la formulación de la tarea a realizar)

Y luego los pasos: 1) Asegúrese de que la máquina esté apagada. Si funciona, haga clic allí y allí. 2) Entonces haz esto.

Si el problema tiene varias soluciones:

En tales casos, la frase introductoria debe contener las palabras:

- "pruebe estas soluciones",
- "prueba lo siguiente",
- "asegúrese de que", etc.

Aquí hay algunos ejemplos de la documentación en inglés:

Título de la página: No puedo activar Parallels Desktop
Cubiertas de tareas: una lista de cosas para verificar
Encabezado de paso: si tiene problemas para activar Parallels Desktop, asegúrese de que ...

Título de la página: Windows parece lento
Cubiertas de tareas: una lista de cosas para probar
Encabezado de paso: si el rendimiento de Windows parece lento, intente lo siguiente ...

Título de la página: un mensaje dice "No hay Mac conectados"
Cubiertas de tareas: varias cosas para verificar o probar
Encabezado de paso: si no ve su Mac en la lista de Mac

Información necesaria para resolver el problema (pasos para la solución)

Esta sección incluye todo lo que el usuario necesita saber y / o emprender.

Si hay varias soluciones:
En tales casos, describa cada método usando viñetas (más sobre esto en la segunda parte de los consejos). Si algún método es complicado y ya lo ha descrito en detalle en otro tema, solo proporcione un enlace.

Si lo que necesita hacer ya se describe en algún otro tema:
Solo dale un enlace a este tema.

Si no hay instrucciones específicas, qué se puede hacer para resolver el problema:
Proporcione cualquier información adicional que pueda ayudar al usuario a descubrir qué podría estar causando el problema.

Conclusión (outro)

En conclusión, puede proporcionar información adicional relacionada con la tarea o las posibles soluciones al problema. Puede leer más sobre el uso de outro en la segunda parte de los consejos .

Uso de gráficos (capturas de pantalla, gráficos, diagramas, etc.)

Las capturas de pantalla y los diagramas pueden ayudar a los usuarios a comprender mejor lo que está escrito en el tema.

Cuando usar gráficos:

En cada paso, no necesita insertar una captura de pantalla: el usuario simplemente no sabrá dónde mirar, comparando constantemente la pantalla y la captura de pantalla.

Las capturas de pantalla deben insertarse cuando ayudan significativamente a comprender lo que está escrito en las instrucciones.

Por ejemplo:

• Cuando necesita mostrar un botón o icono que no tiene nombre en el gua, o no llama la atención de inmediato, o hay varios similares en la pantalla;
• Cuando necesite proporcionar un contexto para la tarea o una explicación visual clara de cómo y cómo se verá al final;
• Si la captura de pantalla le permite comprender o explicar rápidamente algo que requerirá una explicación en palabras demasiado larga y complicada.

Dónde y cómo colocar el horario:

A continuación se presentan algunas recomendaciones sobre dónde y cómo colocar gráficos en la página.

1) Si la captura de pantalla refleja la información conceptual o el resultado de la tarea, puede insertarla en o después de la introducción.

Aquí hay un ejemplo de la documentación en inglés, que muestra un tema que describe el modo de ventana de Windows. Una captura de pantalla que muestra lo que sucederá después de insertar un interruptor de este tipo después de la introducción y antes de las instrucciones en sí, cómo cambiar a este modo:



2) Si la captura de pantalla se refiere a un paso específico en las instrucciones, insértelo después o dentro de este paso:



Si necesita insertar una captura de pantalla de un botón, icono u otro elemento de la interfaz, debe insertarlo después del nombre de este elemento:



No use gráficos para ilustrar cosas obvias.

Específicamente, no use capturas de pantalla para ilustrar:

• Menu
• Iconos, botones y pestañas que tienen un nombre
• Todo lo demás que se puede describir fácil y fácilmente en palabras.

Consejos adicionales para quienes escriben documentación en inglés:


1) Cómo capitalizar títulos:

mayúsculas Hay tres estilos de mayúsculas disponibles: estilo de oración, estilo de título y mayúsculas.

• Mayúsculas al estilo de las oraciones: esta línea proporciona un ejemplo de mayúsculas al estilo de las oraciones.
• Capitalización de estilo de título: esta línea proporciona un ejemplo de capitalización de estilo de título.
• Todas las mayúsculas: ESTA LÍNEA PROPORCIONA UN EJEMPLO DE TODAS LAS MAYÚSCULAS.

No uses mayúsculas para enfatizar.

mayúsculas (estilo de oración): cuando usa mayúsculas de estilo de oración, escriba en mayúscula la primera letra de la primera palabra, así como la primera letra de cualquier nombre propio y adjetivo apropiado.
mayúsculas (estilo de título): utilice mayúsculas de estilo de título para títulos de libros, títulos de partes, títulos de capítulos y títulos de secciones (encabezados de texto).

Siga estas reglas cuando use mayúsculas al estilo de título. Capitaliza cada palabra excepto:

• Artículos (a, an, the), a menos que un artículo sea la primera palabra o siga dos puntos
• Conjunciones de coordinación (y, pero, o, ni, para, todavía, y así)
• La palabra en infinitivos (Cómo conectar su impresora)
• La palabra como, independientemente de la parte del discurso
• Palabras que siempre comienzan con una letra minúscula, como iPhone y iPad.
• Preposiciones de cuatro letras o menos (at, by, for, from, in, into, of, off, on, onto, out, over, to, up y with), excepto cuando la palabra es parte de una frase verbal. Por ejemplo:
  
  Inicie el ComputerLog
  En el servidor
  Comenzó con Parallels Desktop

Capitalizar:

• La primera y la última palabra, independientemente de la parte del discurso:
Para usuarios de linux

Para qué sirven las herramientas de Parallels

• La segunda palabra en un compuesto con guión:

Correcto: eventos de alto nivel, direccionamiento de 32 bits
Incorrecto: Eventos de alto nivel, direccionamiento de 32 bits
Excepciones: incorporado, complemento

• Las palabras son, si, es, eso, que, eso y esto

2) Cómo usar la palabra "clic":

Haga clic en Usar clic para describir el acto de colocar el puntero en un objeto en pantalla y presionar brevemente y soltar el botón del mouse. No use hacer clic en. Como la mayoría de los usuarios saben qué es hacer clic, debe definirlo solo en la documentación diseñada para usuarios principiantes, como tutoriales.
Correcto: haga clic en Mac si desea utilizar el dispositivo USB con Mac OS X.

Incorrecto: apunte a Mac y haga clic en él si desea usar el dispositivo USB en Mac OS X.
haga clic en No usar; use click.

3) ¿Correo electrónico o correo electrónico?

Utiliza el correo electrónico. No uses el correo electrónico.

4) Si o si?

Use if para expresar una condición. Use si expresar alternativas.
Correcto: compruebe si se han instalado Parallels Tools.
Incorrecto: Compruebe si se han instalado Parallels Tools.
Correcto: haga clic en Mac si desea utilizar el dispositivo USB con Mac OS X.

5) Cómo usar nombres de productos:

Siga el estilo de capitalización en el empaque del producto. Use el nombre completo del producto para su primera aparición dentro de una sección de texto (por ejemplo, un capítulo). A partir de entonces, cuando corresponda, use una versión abreviada del nombre del producto.

Por ejemplo: Parallels Desktop 14 para Mac: en la primera aparición dentro de una sección de texto, use Parallels Desktop 14 para Mac.

En casos posteriores, use Parallels Desktop.

Conclusión

En estas 3 partes del manual, intentamos reunir, resumir y estructurar los consejos que ayudarán a que su documentación sea más fácil y comprensible.

No insistimos en que la escritura sea necesaria de esta manera: hay muchos enfoques para la documentación y las técnicas. Mire la configuración y use las que más le convengan.

¡Muchas gracias por su atención e interés!