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:

  • 鈥淣o puedo activar Parallels Desktop鈥 (鈥淣o 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: 鈥淧ara 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!

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


All Articles