Recomendaciones generales y estilo
La documentación técnica tiene un estilo de redacción diferente al periodismo, a la literatura de ensayo o a la escritura comercial (copywritting). Debe ser aséptica, neutra, eficaz y rápida. Para ello hay que ser lo más objetivo posible, evitar cualquier figura literaria, adorno de estilo y simplificar al máximo las expresiones, las estructuras del lenguaje. Para ello, se deben emplear frases cortas con tiempos verbales simples.
Como desconocemos a la persona que va a leer el texto, asumimos como regla general dos cosas, en todo momento.
- Contextualizar al lector para que entienda de lo que hablamos, ya que no conocemos sus conocimientos.
- No des nada por supuesto. El lector no tiene porqué saber cosas que nosotros damos por sabidas a la hora de explicar lo que estamos explicando.
Obviamente no se trata de enseñar al lector a sumar si estamos hablando de operaciones aritméticas complejas en el manual, pero si introducimos por primera vez conceptos como “nodo” o “SNMP” conviene asumir que el lector no sabe lo que significan, y la primera vez, hacer el esfuerzo de hacer una pequeña introducción a dichos conceptos.