Toda la funcionalidad de la codebase —tanto las políticas como el código fuente— DEBE estar descrita en un lenguaje claramente comprensible para aquellos que entienden el propósito del código.
La documentación de la codebase DEBE contener:
Una descripción de cómo instalar y ejecutar el código fuente.
Ejemplos que demuestren la funcionalidad clave.
La documentación del código base DEBERÍA contener:
Una descripción de alto nivel que sea claramente comprensible para una amplia audiencia de interesados, como el público en general y los periodistas.
Una sección que describa cómo instalar y ejecutar una versión independiente del código fuente, incluyendo, si es necesario, un conjunto de datos de prueba.
Ejemplos de todas las funcionalidades.
DEBERÍA haber pruebas de integración continua para la calidad de la documentación.
La documentación de la codebase PUEDE contener ejemplos que hagan que los usuarios quieran empezar a utilizar inmediatamente la codebase.
El código PUEDE ser probado usando ejemplos en la documentación.
Por qué es importante
Los usuarios pueden empezar a usar y contribuir más rápidamente.
Ayuda a la gente a descubrir la codebase, especialmente a quienes se preguntan «¿existe ya un código que haga algo como esto?»
Proporciona transparencia en su organización y procesos.