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.
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.
Qué no hace
- Contribuir directamente a un código más reutilizable y portable (ver Crear código reutilizable y portable).
Cómo probar o hacer tests
- 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.
Responsables de políticas y legislaciones: qué necesitan hacer
- 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.
Profesionales de la dirección de equipos: qué necesitan hacer
- Tratar de usar la codebase.
- Asegurarse de entender tanto la política y el código fuente como la documentación.
Profesionales del desarrollo de software y diseño: qué necesitan hacer
- Comprobar regularmente cómo ha cambiado el código no fuente en la codebase.
- Dar información sobre cómo hacer que la documentación no fuente sea más clara.
Más información (en inglés)
- Guía de documentación por Write the Docs.