Documentar el código

Requisitos

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.

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.

Contribuir directamente a un código más reutilizable y portable (ver Crear código reutilizable y portable).

Otras partes interesadas, profesionales de otras organizaciones públicas y el público en general encuentran la documentación clara y comprensible.
La documentación es generada a partir del código.
Las imágenes y los enlaces son comprobados automáticamente.

Comprobar regularmente cómo ha cambiado el código no relacionado con las políticas en la codebase.
Dar información sobre cómo hacer que la documentación no relacionada con las políticas sea más clara.

Tratar de usar la codebase.
Asegurarse de entender tanto la política y el código fuente como la documentación.