Escribir un manual requiere construir contenido bien escrito para darle claridad al lector.
En el proceso de escritura debemos tener en cuenta la ortografía, la redacción y el estilo o forma de escribir. Podemos tener en cuenta los siguientes recomendaciones
Para escribir con ortografía:
| Tip | Descripción | Consultas, trucos, ejemplos |
|---|---|---|
| Correctores | Utilizar un corrector de estilo antes de publicar el contenido nos permite filtrar errores básicos de ortografía o de mal tecleado | Word- Correctores de ortografía y gramática |
| Uso de las palabras | El uso correcto de las palabras nos ayuda a dar el contexto adecuado de lo qué queremos decir o simplemente nos ayuda a confirmar alguna duda gramatical (sinónimos, conjugación correcta, ortografía) | Diccionario de la Lengua Española |
| Reglas de Acentuación | Utiliza las reglas de acentuación para validar el correcto acento en las palabras. No olvida palabras Agudas (común), graves(árbol) y esdrújulas(esporádico) | TIP: Todas las palabras en español, de entrada, llevan acento: Siempre hacemos más fuerza en una sílaba. Pronuncia la palabra en voz alta de forma exagerada, separando sus sílabas. Si dudas, repítelo poniendo la fuerza en cada una de ellas. |
| Concordancia en género y número | Todas las palabras, sustantivos, adjetivos, verbos deben concordar en género (masculino, femenino) y número | EJEMPLO: “Las políticas configuradas en Aranda Security evaluan los niveles de cumplimiento de aplicaciones de seguridad”. |
| Uso de la Puntuación | El correcto uso de los signos de puntuación como, puntos, comas, puntos y comas, entre otros, permiten que la lectura sea clara y fácil de entender | EJEMPLO: “Al registrar los campos haga clic en el botón Probar conexión. Si la conexión fue exitosa podrá visualizar el mensaje: La información quedó completa”. |
| No usar pronombres en primera persona | Evita el uso de pronombres en primera persona: “yo”, “mi”, “mío”, “mío”, “nosotros”, “nuestro”, “nuestro”. | ANTES: “En esta vista podemos observar fecha del último reporte enviado al dispositivo”. DESPUÉS: “En esta sección podrá visualizar la fecha del último reporte enviado al dispositivo”. |
Para redactar correctamente:
La redacción es un proceso de organización jerárquica de la ideas que ayuda a estructurar y darle sentido a un texto.
No hay una sóla forma de redactar correctamente, pero un documento de caracter instructivo como un manual, debe considerar los siguientes lineamientos:
| Tip | Descripción | Consultas |
|---|---|---|
| Pensar en el Otro | Antes de escribir una idea o describir un proceso debe pensar para quién escribe. Si el destinatario del contenido es un usuario final, el lenguaje debe ser preciso y no debe asumir que el lector conoce por defecto como usted, el funcionamiento de la aplicación. |
EJEMPLO: “Un usuario de Aranda Security debe considerar tres etapas para la gestión y seguimiento de las políticas de cumplimiento”. |
| Texto descriptivo | El tipo de texto a utilizar en un manual es de caracter descriptivo, donde predomnina un lenguaje concreto y claro para describir el desarrollo de una funcionalidad o la explicación de un proceso | EJEMPLO: “La definición y configuración de políticas de Seguridad permiten establecer mecanismos de diagnóstico,control y protección de la información en diferentes niveles”. |
| Formulación de preguntas | La definición y redacción de ciertos conceptos de la funcionalidad pueden implementarse a con la resolución a ciertos interrogantes para determinar de manera puntual qué hace, qué significa o cómo utilizo determinada funcionalidad del producto. |
EJEMPLO: “¿Cómo Asociar Usuarios en AVS? Para agregar uno o más usuarios a un grupo de soporte, seleccione el campo de búsqueda Asociar usuarios, al hacerlo, se despliegan todos los usuarios registrados en el sistema”. |
| Modo verbal imperativo | Por ser un documento tipo instructivo, los verbos utilizados expresan una orden o una prohibición | EJEMPLO: “Ingrese a la consola de Aranda Security Compliance con un usuario con rol de administrador , en la sección de Configuración del menú principal, seleccione la opción Licenciamiento”. |
| Narrador en tercera persona | La descripción del proceso debe efectuarse en tercera persona sin involucrarse en la narración. Escribir en tercera persona permite realizar una descripción más acertada. | EJEMPLO: “Administre las licencias adquiridas por el cliente y genere la solicitud de licencias para realizar una adecuada gestión de los procesos de soporte remoto de la organización”. |
| Tiempo presente atemporal | El tiempo verbal preferido es el presente, atemporal; se refiere a hechos sin alcance de tiempo. Es utilizado para presentar o decribir características, designar verdades, indicar acciones | EJEMPLO: “En la imagen encuentra el listado de usuarios registrados”. |
| Estructura Narrativa | Cada oración debe estar bien estructuada (sujeto-predicado y complementos) y la idea desarrollada debe ser enunciada y concluida | EJEMPLO: La solicitud de cambios (Pull Request) permite mantener un proyecto estable y actualizado |
| Uso de sinónimos | Evite repetir palabras en el contexto de un mismo párrafo, utilizando sinónimos o expresiones similares. | ANTES: Se realizó un ajuste en la consola, se implementa ajuste que permite a los usuarios descargar los campos. DESPUÉS: Se realizó un ajuste en la consola, que permite a los usuarios descargar los campos. |
| Balance en el contenido | La información desarrollada en un documento debe mantener un equilibrio, ser concreto y no repetitivo. Demasiada información no garantiza la permanencia del lector . Información reducida da la impresión de un contenido incompleto. . | EJEMPLO: “Una política es una entidad que define las reglas y condiciones asociadas a componentes de seguridad, que se aplican a un programa bajo criterios que cumplen los marcos regulatorios de protección de la información”. |
⚐ Nota:
- 1. El responsable de generar los contenidos tiene un status comunicativo mayor al del usuario y como experto en el tema conoce el funcionamiento del producto. y esta en la capacidad de redactar desde una visión global más no personal.
- 2. El redactor No debe escribir como habla. Las frases no deben seguir el patrón de una conversación sino el de la redacción|