Por qué la documentación debe vivir junto al código

Esa idea proviene de una práctica común en ingeniería de software y desarrollo ágil.

Martin Fowler — En sus artículos sobre "Self-Documenting Code" y "Continuous Integration", Fowler sugiere que la documentación debe estar “lo más cerca posible del código” para mantenerse actualizada y  Fowler promueve documentar dentro del código (por ejemplo, con comentarios o docstrings), o en el mismo repositorio (por ejemplo, usando README o Markdown junto al código fuente).

Kent Beck — En Extreme Programming Explained, Beck también insiste en que la mejor documentación es el código mismo, y que cualquier documentación adicional debe estar “junto al código que describe” para evitar que quede obsoleta.

Joel Spolsky — En su ensayo “Where does documentation live?”, Joel recomienda mantener la documentación cerca del código en el control de versiones, por la misma razón: coherencia y mantenimiento.