La documentación mide si quien llega por primera vez puede aprender qué es un proyecto y cómo usarlo. El software sin documentar externaliza su coste a cada usuario; el software documentado escala el conocimiento de sus mantenedores. Para una decisión de dependencia, la documentación es además evidencia de esmero — los proyectos que se explican a sí mismos tienden a ser proyectos que se mantienen a sí mismos.
- Categoría: Calidad de Ingeniería (40 % dentro de la categoría)
- Peso en el índice general: 8 %
- Clave de la métrica:
documentation
Cómo se calcula el valor
Una lista de verificación ponderada:
| Componente | Peso | Evidencia |
|---|---|---|
| README | 30 | un archivo README en la raíz del repositorio |
| Directorio de documentación | 25 | un directorio docs/ (o equivalente) |
| Sitio de documentación / página del proyecto | 15 | un sitio de documentación o web del proyecto enlazado desde el repositorio |
| Descripción del repositorio | 10 | la descripción de una línea configurada en GitHub |
| Topics | 10 | topics de GitHub asignados |
| Wiki | 10 | wiki del repositorio habilitada |
Las capas, de lo esencial a lo descubrible
- El README (30) es la puerta de entrada; nada más se lee si falta.
- Un directorio de docs (25) marca una documentación que creció más allá de un archivo — normalmente guías, referencia o notas de arquitectura.
- Un sitio de documentación (15) señala inversión sostenida: documentación renderizada y navegable para usuarios, no solo para visitantes del repositorio.
- Descripción, topics y wiki (30 en conjunto) son metadatos de descubribilidad: determinan si el proyecto puede siquiera encontrarse y clasificarse — por personas, por índices de paquetes y, cada vez más, por herramientas de IA.
Cómo leer el resultado
- Lo que se mide es la presencia, no la calidad de la prosa — el límite honesto de la inspección externa (véase señales, no garantías).
- Conviene leerla en cruce con la salud de la comunidad: el README se solapa como fundamento compartido, pero las dos métricas responden preguntas distintas — ¿puede aprenderse? frente a ¿puede participarse?
Cómo mejorar el valor
- Mantener un README sustantivo: propósito, instalación, ejemplo mínimo y enlaces para seguir.
- Trasladar la documentación en crecimiento a
docs/y publicarla como sitio (GitHub Pages o cualquier generador) — los dos pasos juntos suman 40 puntos. - Configurar la descripción y los topics del repositorio; habilitar la wiki allí donde encaje con el flujo de trabajo del proyecto.
Relacionado: salud de la comunidad · Calidad de Ingeniería