Precisión:
* corrección fáctica: La información presentada debe ser verdadera y actualizada. La información desactualizada o incorrecta es peor que ninguna documentación.
* consistencia: La documentación debe usar terminología, estilo y formato consistentes en todo momento.
integridad:
* cubre todos los aspectos relevantes: Incluye toda la información necesaria para que la audiencia prevista comprenda y use el tema documentado. Esto puede incluir configuración, uso, solución de problemas, limitaciones y conceptos relacionados.
* Detalle suficiente: Proporciona suficiente detalle para ser útil, evitando la brevedad innecesaria o la verbosidad abrumadora. El nivel de detalle debe ser apropiado para el público objetivo.
Comprensión:
* Claridad y concisión: Utiliza un lenguaje claro y simple, evitando la jerga o los términos técnicos a menos que sea absolutamente necesario (y luego definirlos).
* Organización lógica: La información se presenta de manera lógica y fácil de seguir, a menudo utilizando encabezados, subtítulos y ayudas visuales.
* bien estructurado: Fácil de navegar y encontrar información específica rápidamente (por ejemplo, a través de índices, tablas de contenido, funcionalidad de búsqueda).
* Idea para la audiencia: Escrito en un nivel de comprensión adecuado para el público objetivo (principiante, intermedio, experto).
Mantenimiento:
* Fácil de actualizar: La documentación debe ser fácil de actualizar y mantener actualizado a medida que evoluciona el tema documentado. El uso de un sistema de control de versiones es muy recomendable.
* modular y reutilizable: Los componentes de la documentación se pueden reutilizar en diferentes contextos.
* usa un formato manejable: Elegir el formato correcto (por ejemplo, Markdown, reestructuredText, un wiki) es importante para facilitar la edición y la representación.
Otros aspectos importantes:
* Accesibilidad: La documentación debe ser accesible para las personas con discapacidades, siguiendo las pautas de accesibilidad.
* Ejemplos e ilustraciones: El uso de ejemplos, diagramas, capturas de pantalla y otras ayudas visuales puede mejorar significativamente la comprensión.
* Funcionalidad de búsqueda: Si la documentación es grande, proporcionar una función de búsqueda robusta es crucial.
* Versión: Indicando claramente la versión del sujeto documentado.
En resumen, una buena documentación anticipa las necesidades de sus usuarios y les ayuda a tener éxito en sus tareas. Es una inversión que vale la pena en costos de soporte reducidos, mayor satisfacción del usuario y una adopción más rápida del producto o sistema documentado.