Documentar una API como parte del producto

Metadatos de la lección

Autoría:: Ignacio Slater-Muñoz
Última actualización:: 27 de abril de 2026

Cambios recientes:

490303b · 27 de abril de 2026 · 📘 docs: Update changelog for version 0.18.0 with new API documentation lesson and course structure improvements ( GitLab / GitHub )
0aca4df · 27 de abril de 2026 · 📘 lesson(api-design/docs): Improved lesson on API documentation and references ( GitLab / GitHub )
c667fc0 · 26 de abril de 2026 · 📘 docs: Update lesson metadata and enhance API documentation with key points on design and usage ( GitLab / GitHub )

Abstract

En la lección anterior vimos que una API publicada crea compromisos y que evolucionarla exige pensar en compatibilidad. Esta lección cierra esa secuencia mostrando que la documentación es el lugar donde esos compromisos se vuelven legibles para quienes usan la biblioteca.

Una API publicada no solo expone funciones, tipos o rutas: también crea expectativas y restricciones. Documentarla bien significa describir el contrato observable, escribir ejemplos útiles y verificables, explicar cambios y migraciones, mantener la documentación junto con la API y diseñar páginas que respondan a la forma real en que las personas leen documentación técnica.

Esta lección no está pensada como una lista para memorizar ni como una lectura que se deja atrás al terminar la unidad. Su objetivo es ofrecer criterios para tomar mejores decisiones al escribir documentación, reconocer cuándo una página cumple una función y saber dónde profundizar. Puedes volver a ella como pauta de revisión cuando documentes APIs en el curso o en proyectos reales.

La documentación completa el contrato de la API

Documentar es especificar comportamiento

Una firma pública muestra cómo llamar una operación, pero no siempre explica qué promete. La documentación completa el contrato de una API al declarar significado, restricciones, errores y garantías observables.

Una API bien nombrada reduce ambigüedad, pero no responde todas las preguntas. Por ejemplo, una función como parseVersion(input: String): VersionparseVersion(input: String): Version parece clara hasta que necesitamos saber qué formatos acepta, si ignora espacios, qué ocurre con una versión inválida o si el formato aceptado cambió entre versiones.

Una firma legible todavía puede estar incompleta

fun parseVersion(input: String): Version

fun parseVersion(input: String): Version

La declaración dice cómo invocar la función, pero no define por sí sola las reglas de validez, error ni compatibilidad.

Documentar vuelve explícito el contrato observable

/**
 * Parses a semantic version string.
 *
 * Accepts versions in the form "major.minor.patch", where each component
 * is a non-negative integer without surrounding whitespace.
 *
 * ## Usage:
 * ```kotlin
 * val version = parseVersion("1.4.2")
 *
 * println(version.major) // 1
 * println(version.minor) // 4
 * println(version.patch) // 2
 * ```
 *
 * @param input Version string to parse.
 * @return The parsed [Version].
 * @throws IllegalArgumentException when input does not follow the expected format.
 */
fun parseVersion(input: String): Version

/**
 * Parses a semantic version string.
 *
 * Accepts versions in the form "major.minor.patch", where each component
 * is a non-negative integer without surrounding whitespace.
 *
 * ## Usage:
 * ```kotlin
 * val version = parseVersion("1.4.2")
 *
 * println(version.major) // 1
 * println(version.minor) // 4
 * println(version.patch) // 2
 * ```
 *
 * @param input Version string to parse.
 * @return The parsed [Version].
 * @throws IllegalArgumentException when input does not follow the expected format.
 */
fun parseVersion(input: String): Version

La documentación distingue cómo llamar la API de qué comportamiento puede esperar quien la consume.

Un cambio de comportamiento también es un cambio de API

Si una operación conserva la misma firma pero cambia su política de errores, su orden de resultados, el formato que acepta o el significado de un valor por defecto, la API cambió para quienes dependían de ese comportamiento. La documentación es el lugar donde esas promesas se hacen visibles.

Qué debe documentar una API pública

La referencia debe responder preguntas de uso

Documentar una API pública no consiste en repetir la firma con otras palabras. La referencia debe explicar qué representa cada elemento público, qué promete y qué necesita saber una persona externa para usarlo correctamente.

No todas las operaciones necesitan el mismo nivel de detalle. Una función pura y pequeña puede requerir solo una explicación breve, mientras que una operación con errores, efectos secundarios, reglas de compatibilidad o decisiones de formato necesita un contrato más explícito. La pregunta central no es «¿qué puedo copiar desde el código?» , sino «¿qué necesita saber una persona externa para depender de esto sin leer la implementación?» .

Rúbrica práctica para documentar elementos públicos

Documenta estos aspectos según lo que resulte relevante para el uso correcto:

Propósito: qué problema resuelve el tipo, función o configuración.
Contrato: entradas válidas, precondiciones, postcondiciones e invariantes.
Fallas: errores, excepciones, resultados inválidos y casos límite.
Costos y efectos: complejidad, efectos, I/O, mutación o bloqueo, cuando afecten el comportamiento observable.
Evolución: versión de incorporación, deprecación, reemplazo y notas de migración.
Uso: ejemplos mínimos que muestren la operación en contexto.

La diferencia se entiende mejor al contrastar dos casos. Una función pública pequeña puede necesitar documentación breve; una operación de parsing con reglas de formato y errores exige un contrato mucho más explícito.

Un elemento público simple puede requerir menos detalle

/**
 * Checks if a version is stable.
 *
 * A version is stable if it contains only major, minor and patch components
 * with no pre-release or build metadata.
 *
 * @param version The version to check.
 * @return true if the version is stable, false otherwise.
 */
fun isStable(version: Version): Boolean

/**
 * Checks if a version is stable.
 *
 * A version is stable if it contains only major, minor and patch components
 * with no pre-release or build metadata.
 *
 * @param version The version to check.
 * @return true if the version is stable, false otherwise.
 */
fun isStable(version: Version): Boolean

Aquí basta documentar propósito, criterio general y un ejemplo breve. Probablemente no hagan falta secciones de errores, I/O, compatibilidad o migración.

Una operación de parsing necesita un contrato más explícito

/**
 * Parses a stable version in the form MAJOR.MINOR.PATCH.
 *
 * The parser accepts only three non-negative integer components separated by dots.
 * It does not trim surrounding whitespace and does not accept prefixes,
 * pre-release labels or build metadata.
 *
 * @param input Version string to parse.
 * @return The parsed [Version].
 * @throws VersionFormatException when [input] does not match the public format.
 */
fun parseVersion(input: String): Version

/**
 * Parses a stable version in the form MAJOR.MINOR.PATCH.
 *
 * The parser accepts only three non-negative integer components separated by dots.
 * It does not trim surrounding whitespace and does not accept prefixes,
 * pre-release labels or build metadata.
 *
 * @param input Version string to parse.
 * @return The parsed [Version].
 * @throws VersionFormatException when [input] does not match the public format.
 */
fun parseVersion(input: String): Version

En este caso sí se vuelven relevantes el formato aceptado, los errores, los límites del parser y lo que quien consume no debería asumir.

No todo lo que una persona quiere saber cabe en la referencia de la API. Cuando la pregunta es cómo empezar, cómo resolver una tarea concreta o por qué una decisión de diseño existe, otras clases de documentación reparten mejor la carga explicativa.

Para profundizar este bloque

Si quieres estudiar con más detalle cómo escribir contratos y documentación de API, revisa la referencia de Reddy sobre documentación de APIs y, como complemento metodológico, los principios de Write the Docs. Las dos aparecen al final de la página en Referencias.

No toda documentación cumple la misma función

La documentación no es un solo artefacto

Una biblioteca necesita varias formas de documentación porque las personas llegan con preguntas distintas: aprender, resolver una tarea, consultar un contrato, entender una decisión de diseño, migrar, contribuir o evaluar si pueden usar el proyecto.

Una referencia de API es necesaria, pero rara vez basta. Su función principal es precisar contratos: qué elementos públicos existen, qué reciben, qué devuelven, qué errores pueden producir y qué garantías ofrecen. Para usar una biblioteca en problemas reales, también se necesitan documentos que expliquen cómo combinar esas piezas en flujos completos.

Una forma práctica de distinguir estos documentos es preguntar qué duda resuelven: «¿cómo empiezo?» , «¿cómo hago esta tarea?» , «¿qué garantiza esta API?» , «¿por qué está diseñado así?» o «¿qué cambió entre versiones?» .

README o getting started: explica qué problema resuelve la biblioteca y cómo lograr el primer uso exitoso.
Tutoriales: acompañan el primer aprendizaje mediante un recorrido guiado y progresivo.
Guías prácticas: explican cómo completar una tarea concreta, como configurar una integración, publicar un paquete o migrar desde una versión anterior.
Referencia de API: documenta con precisión los elementos públicos, sus contratos, sus invariantes y sus límites de uso.
Explicaciones conceptuales: desarrollan el modelo mental de la biblioteca: sus abstracciones, decisiones de diseño, límites, trade-offs y relación entre sus componentes.
Changelog, notas de versión y guías de migración: registran cambios relevantes, explican su impacto y muestran cómo adaptar código existente entre versiones.
Troubleshooting: ayuda a reconocer fallas frecuentes y decisiones de diagnóstico.

Los documentos de proyecto también son documentación

Algunos documentos no describen directamente una función, pero sí afectan la decisión de adoptar, distribuir, auditar o colaborar en una biblioteca. Conviene tratarlos como documentación pública del proyecto, aunque no sean el centro de la referencia de API.

LICENSE: declara bajo qué condiciones se puede usar, copiar, modificar y redistribuir el código.
CONTRIBUTING.md: explica cómo proponer cambios, ejecutar verificaciones y respetar las convenciones del proyecto.
CODE_OF_CONDUCT.md: define expectativas de participación y criterios para cuidar la interacción dentro del proyecto.
SECURITY.md: indica cómo reportar vulnerabilidades o problemas sensibles sin exponer detalles prematuramente.

Ingredientes y recetas

Piensa la referencia como una lista de ingredientes: es precisa y necesaria, pero no siempre enseña a cocinar. Las guías, ejemplos y tutoriales muestran recetas: cómo combinar la API para resolver problemas concretos sin obligar a deducirlo todo desde declaraciones aisladas.

Cuando la referencia ya no puede cargar sola con todas las dudas del lector, el tipo de documento importa: cada página debe asumir una parte distinta de la explicación para que el conjunto siga siendo legible.

Usa esta página como punto de partida

Esta sección no busca cerrar el tema, sino darte un mapa para seguir aprendiendo. Para profundizar, revisa primero “How to Write Software Documentation” y “Make a README” , que ayudan a distinguir entre referencia, guías y material introductorio. Luego, cuando trabajes evolución de APIs, vuelve sobre “Keep a Changelog” para conectar documentación, versiones y migración.

Ejemplos ejecutables

Una biblioteca debería incluir ejemplos que se puedan ejecutar

Un ejemplo no debería ser solo un fragmento decorativo en la documentación. Cuando el ejemplo puede compilarse, ejecutarse o verificarse automáticamente, también protege la promesa pública de la API.

Muchas personas aprenden una biblioteca copiando un ejemplo mínimo, adaptándolo a su caso y luego revisando la referencia cuando necesitan más detalle. Por eso los ejemplos forman parte de la experiencia de consumo de la biblioteca: muestran el camino esperado antes de explicar todas las reglas.

Una biblioteca puede ofrecer ejemplos ejecutables de distintas formas. No todas sirven para lo mismo, pero todas reducen la distancia entre lo que la documentación dice y lo que el código realmente permite.

Formas comunes de incluir ejemplos ejecutables

Un módulo o proyecto de ejemplos, separado del código de producción, que muestre casos de uso completos de la API.
Documentación ejecutable, donde los fragmentos publicados se compilan o se ejecutan como parte de la verificación del proyecto.
Notebooks, útiles cuando el ejemplo necesita exploración interactiva, visualización o una explicación paso a paso.

Los ejemplos deberían vivir fuera del código de producción

root
├── library
│   └── src
│       └── main
│           └── kotlin
├── examples
│   └── basic-usage
│       └── src
│           └── main
│               └── kotlin
└── docs
    └── notebooks

root
├── library
│   └── src
│       └── main
│           └── kotlin
├── examples
│   └── basic-usage
│       └── src
│           └── main
│               └── kotlin
└── docs
    └── notebooks

Separar los ejemplos evita mezclar responsabilidades: la biblioteca define la API; los ejemplos muestran cómo consumirla desde fuera.

Un ejemplo ejecutable muestra un uso completo

fun main() {
    val version = parseVersion("1.4.2")

    println(version.major) // 1
    println(version.minor) // 4
    println(version.patch) // 2
}

fun main() {
    val version = parseVersion("1.4.2")

    println(version.major) // 1
    println(version.minor) // 4
    println(version.patch) // 2
}

El fragmento no solo presenta la función: muestra una entrada válida, el objeto resultante y una forma observable de usar el resultado.

Los ejemplos solo ayudan mientras siguen siendo ciertos. Por eso conviene tratarlos como parte de la verificación del producto y no como texto decorativo que se copia una vez y luego se olvida.

Documentación mantenible: cerca, única y actual

La documentación también tiene arquitectura

Si la documentación es parte del producto, debe poder mantenerse. Eso exige decidir dónde vive, cuál es la fuente canónica de cada dato y cómo se mantiene sincronizada con el código.

Cerca: la documentación relacionada con una API debería vivir lo bastante cerca del código para que un cambio invite a actualizar ambos.
Única: los datos canónicos — valores aceptados, políticas de compatibilidad, garantías y restricciones — no deberían mantenerse copiados en lugares que puedan divergir.
Actual: una explicación obsoleta crea falsa confianza y puede ser peor que una ausencia visible.

Cuando sea posible, la documentación debería verificarse automáticamente: ejemplos que compilan, enlaces revisados, referencias generadas desde la API pública o pruebas que alerten cuando una promesa documentada deja de cumplirse.

ARID: aceptar repetición en documentación

En código solemos aplicar el principio DRY: evitar duplicar conocimiento para que una misma regla no deba mantenerse en varios lugares. Si la validación de una opción está repetida en tres funciones, cualquier cambio puede dejar una copia obsoleta.

En documentación aparece una tensión distinta. Quien lee una página no siempre sigue el recorrido completo del curso ni conoce todas las páginas relacionadas. Por eso, el principio ARID (Accept Repetition In Documentation) propone aceptar cierta repetición cuando ayuda a que una explicación sea comprensible por sí misma.

ARID no significa repetir sin control. El punto es repetir contexto útil, no duplicar datos canónicos. Un tutorial puede repetir brevemente qué hace una opción para que el ejemplo sea legible. Pero la lista completa de valores aceptados, la política de soporte o una garantía de compatibilidad deberían tener una fuente principal que se actualice con cuidado.

Regla práctica

Repite contexto cuando ayude a leer una página localmente, pero enlaza o genera los datos que deben permanecer exactos: firmas, valores aceptados, versiones soportadas, garantías de compatibilidad y políticas de deprecación.

Documentación incorrecta daña confianza

Si la documentación dice que una opción acepta "strict""strict" y la versión actual lo rechaza, quien consume la biblioteca pierde tiempo intentando encontrar su error. En realidad, el problema era del producto: prometió algo que ya no cumplía.

Incluso una documentación exacta puede fallar si nadie la puede encontrar a tiempo. Por eso el contenido correcto necesita una estructura que permita llegar a la respuesta desde un error, una búsqueda, un enlace compartido o una guía de migración.

Para continuar practicando

Si quieres practicar mantenimiento documental como parte del producto, revisa Keep a Changelog para comunicar cambios y SPDX License List para estandarizar información de licencia. Puedes usarlas como checklist en tu próximo proyecto.

Lenguaje inclusivo en la documentación

Las palabras también diseñan la experiencia de uso

La documentación de una biblioteca no solo transmite información técnica. También comunica si distintas personas son bienvenidas a usar el proyecto, reportar problemas, contribuir y aprender desde él. Por eso, la terminología debería ser precisa, clara y respetuosa con distintas experiencias, culturas y comunidades.

En documentación técnica, el problema no siempre está en la intención de quien escribe, sino en el efecto que ciertos términos pueden tener sobre quienes leen. Si una palabra arrastra asociaciones innecesarias, excluyentes o ambiguas, suele ser mejor reemplazarla por una alternativa más descriptiva.

Preferir precisión antes que metáforas cargadas

Una buena regla práctica es elegir palabras que describan la función real del concepto. En vez de depender de metáforas heredadas, conviene nombrar el comportamiento observable: qué elemento controla, cuál replica, qué se acepta, qué se rechaza o qué condición se está verificando.

allow list / block list en vez de whitelist / blacklist: describe qué elementos se aceptan o bloquean.
primary / replica en vez de master / slave: describe roles dentro de una arquitectura distribuida.
main branch en vez de master branch: nombra la rama principal sin depender de jerarquías innecesarias.

Más ejemplos de lenguaje preciso

placeholder, sample o test value en vez de dummy value: describe el propósito de un valor de ejemplo.
consistency check en vez de sanity check: describe mejor la operación que expresiones coloquiales.

No reemplazar términos de forma mecánica

El lenguaje inclusivo no consiste en aplicar una tabla de sustituciones sin pensar. El reemplazo debe conservar precisión técnica, compatibilidad con el ecosistema y claridad para quien lee. La pregunta no es solo «¿esta palabra aparece en una lista?» , sino «¿existe una alternativa más precisa, clara y respetuosa para este contexto?» .

Si un término ya forma parte de una API pública, una migración responsable puede requerir alias, deprecación, notas de versión y una guía breve de transición. Cambiar nombres públicos sin una estrategia de compatibilidad puede romper código existente, aunque el nuevo nombre sea mejor.

Criterio para revisar nombres y documentación

Antes de publicar una API o una página de documentación, conviene revisar si los nombres, ejemplos y mensajes de error son comprensibles desde distintas perspectivas.

Evita metáforas innecesarias cuando exista una descripción más directa.
Usa formulaciones neutras cuando el género no sea relevante.
Escoge nombres de ejemplo diversos y culturalmente variados.
Evita asociar colores, edad, capacidad, procedencia o identidad con cualidades positivas o negativas.
Revisa mensajes de error, nombres de tests y datos ficticios: también forman parte de la experiencia de uso.

Revisar el lenguaje no es un gesto aislado: también forma parte de la experiencia de lectura. Si una página no está escrita para poder buscarse, escanearse y citarse, la precisión pierde parte de su valor práctico.

Para profundizar en naming inclusivo

Inclusive Naming Initiative puede servirte como referencia de revisión cuando quieras proponer renombres públicos con estrategia de migración en vez de cambios abruptos. Lo encontrarás en Referencias.

Diseñar para lectura real

La documentación también es experiencia de uso

Quien lee documentación no siempre sigue un camino lineal. Busca, escanea, copia ejemplos, llega desde errores, revisa cambios y comparte enlaces específicos.

Documentar bien implica escribir para esa lectura real. La información importante debe aparecer donde se necesita, con títulos descriptivos, anclas estables, ejemplos visibles y secciones que permitan encontrar respuestas sin leer todo desde el comienzo.

Para una biblioteca, muchos recorridos empiezan fuera del sitio de documentación: un mensaje de error, una advertencia de deprecación, una búsqueda web, un README, una issue o una revisión de código. Diseñar para lectura real significa conectar esos puntos de entrada con la explicación adecuada.

Principios de lectura práctica

Escaneable: encabezados claros, listas breves y conceptos importantes al principio.
Descubrible: enlaces desde README, errores, paquete, changelog y páginas relevantes.
Direccionable: secciones con anclas que puedan compartirse en issues, revisiones y soporte.
Con contexto mínimo: una sección enlazada debería poder entenderse sin leer toda la página anterior.
Orientada: cada página explicita qué presupone, qué resuelve y hacia dónde continuar.
Honesta en su alcance: cada página debe decir qué cubre, qué no cubre y dónde seguir.

Cuando una API evoluciona, esta experiencia se vuelve aún más importante. La documentación versionada, las notas de deprecación y las guías de migración ayudan a que actualizar no sea una sorpresa, sino una transición comprensible.

Conclusiones

El recorrido de esta unidad fue acumulativo: partimos de los artefactos de software, pasamos a ver las bibliotecas como productos reutilizables, después tratamos sus APIs como contratos públicos y, más tarde, analizamos cómo evolucionan sin romper compatibilidad. Esta lección cierra ese bloque al mostrar que la documentación es la forma legible de esos compromisos.

La documentación útil combina distintos artefactos. La referencia precisa contratos; los tutoriales guían el primer aprendizaje; las guías prácticas resuelven tareas concretas; las explicaciones construyen modelo mental; y las notas de versión o migración hacen visible el cambio. Cuando estos documentos se mantienen cerca del código, se verifican con ejemplos ejecutables y usan lenguaje claro e inclusivo, la API se vuelve más confiable y más fácil de adoptar.

Puntos clave

La documentación completa el contrato de una API al declarar comportamiento observable, restricciones, errores, garantías y supuestos de compatibilidad.
No todos los elementos públicos requieren el mismo nivel de detalle: la documentación debe responder las preguntas necesarias para usar cada API correctamente.
Una biblioteca necesita varios tipos de documentación: referencia, tutoriales, guías prácticas, explicaciones, troubleshooting, changelog y guías de migración.
Los ejemplos ejecutables reducen la distancia entre lo que la documentación promete y lo que el código realmente permite.
La documentación mantenible debe tener fuentes canónicas claras, vivir cerca del código relacionado y actualizarse cuando cambia el comportamiento público.
El lenguaje de la documentación debe ser preciso, claro e inclusivo, sin aplicar reemplazos mecánicos que dañen la comprensión o la compatibilidad.
Diseñar para lectura real significa escribir páginas escaneables, descubribles, direccionables y útiles aun cuando alguien llegue desde un error, una búsqueda, una issue o una guía de migración.

Reflexión de cierre

No necesitas memorizar cada criterio de esta lección. Lo importante es aprender a volver a estas preguntas cuando estés escribiendo documentación: «¿qué promesas necesita encontrar una persona que usa la biblioteca para depender de ella sin leer la implementación?» , «¿esta página resuelve la duda correcta?» y «¿qué debería enlazar, verificar o explicar mejor?» .

Usa esta página como una pauta de revisión: para las APIs que diseñes en el curso, para bibliotecas que publiques y para proyectos reales donde la documentación también sea parte del producto.

¿Con ganas de más?

Referencias recomendadas

“ Documentation principles ” en Write the Docs

Como criterio de revisión, los principios de Write the Docs ayudan a convertir las ideas de la lección en decisiones más operativas. La guía organiza la calidad documental en torno al contenido, las fuentes, las publicaciones y el conjunto completo de documentos: documentar temprano, aceptar cierta repetición útil, escribir para escaneo, mantener ejemplos y consistencia, ubicar las fuentes cerca del código, evitar solapamientos, hacer las páginas descubribles y enlazables, y asegurar que el conjunto responda las preguntas probables de quien usa el software.
“Documentation” (pp. 415–442) en API design for C++ por Martin Reddy

Reddy permite profundizar la tesis central de la lección: la documentación no solo acompaña a una API, sino que completa su especificación. El texto desarrolla qué comportamientos conviene documentar, cómo expresar contratos, precondiciones, postcondiciones, cambios de comportamiento y garantías de uso, y qué tipos de documentación ayudan a encontrar respuestas sin leer la implementación. También muestra cómo estas decisiones se traducen en herramientas concretas como Doxygen y en criterios prácticos de escritura, navegación, ejemplos, versionado e inclusión.

Referencias adicionales

“ Contributor Covenant: A Code of Conduct for Digital Communities ” en Organization for Ethical Source por Coraline Ada Ehmke

En proyectos colaborativos, el CODE_OF_CONDUCT.md documenta condiciones de participación alrededor de la biblioteca. Contributor Covenant ofrece un modelo ampliamente usado para explicitar valores, expectativas de trato, mecanismos de reporte y políticas de aplicación. Después de la lección, ayuda a ver que documentar una biblioteca no solo significa explicar su API: también implica comunicar cómo se participa en torno a ella y qué acuerdos sostienen una comunidad segura, clara e inclusiva.
“ How to write software documentation ” en Write the Docs

Para llevar la discusión a una primera documentación publicable, esta guía de Write the Docs ofrece un punto de partida práctico. Explica por qué documentar ayuda a recordar decisiones, conseguir usuarios, facilitar contribuciones y mejorar el diseño; luego propone qué incluir para que una biblioteca sea adoptable: problema que resuelve, ejemplo mínimo, instalación, enlaces al código y al seguimiento de issues, formas de soporte, guía de contribución y licencia. También incluye una plantilla de README reutilizable.
“ Inclusive Naming Initiative ” en The Inclusive Naming Initiative

Para revisar nombres públicos con más criterio, Inclusive Naming Initiative complementa la parte de la lección dedicada al lenguaje inclusivo. El recurso reúne términos problemáticos, alternativas recomendadas, niveles de prioridad y materiales para implementar cambios de nombre en proyectos y organizaciones. Después de estudiar documentación de APIs, sirve para revisar nombres públicos, ejemplos, guías y textos de proyecto sin hacer reemplazos improvisados: ayuda a decidir qué cambiar, por qué hacerlo y cómo mantener consistencia durante la migración.
“ Keep a Changelog ” en keepachangelog.com por Olivier Lacan

Para comunicar la evolución de una biblioteca, Keep a Changelog trata el historial de cambios como documentación pública orientada a personas. Propone versiones en orden cronológico inverso, fechas claras, enlaces por versión, una sección Unreleased y categorías como Added, Changed, Deprecated, Removed, Fixed y Security. Después de esta lección, resulta especialmente útil para comunicar cambios de comportamiento, deprecaciones y rupturas sin obligar a quienes usan la API a interpretar un log de commits.
“ Make a README ” en www.makeareadme.com por Danny Guo

El README funciona como la primera experiencia de muchas personas con una biblioteca, y esta referencia ayuda a evaluarlo desde esa función. La página explica qué es, por qué conviene escribirlo antes de publicar el proyecto y qué preguntas debería responder: qué hace el software, cómo instalarlo, cómo usarlo, dónde pedir soporte, cómo contribuir y bajo qué licencia se distribuye. Además, ofrece una plantilla editable y una lista de secciones posibles para decidir qué debe quedar en el README y qué conviene mover a una documentación más completa.
“ SPDX License List ” en Linux Foundation Collaborative Projects por SPDX Project

La licencia también forma parte de la documentación que hace adoptable una biblioteca. La lista SPDX reúne licencias y excepciones comunes con un identificador corto estandarizado, nombre completo, texto de licencia y URL canónica permanente. Después de la lección, sirve para entender por qué un archivo LICENSE, un campo de metadatos o un comentario de cabecera deberían usar nombres reconocibles y verificables, en vez de descripciones informales que vuelven ambigua la adopción, redistribución o auditoría del proyecto.