Mal consejo: ¬Ņc√≥mo escribir documentaci√≥n t√©cnica?

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:

imagen

‚ÄĘ 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)

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


All Articles