Los ejemplos son la mejor documentación

• Cuando los desarrolladores buscan documentación, en el 95% de los casos basta con un ejemplo sencillo, pero solo en un 5% de los casos se pueden encontrar ejemplos en la fuente oficial
• La documentación técnica oficial suele estar escrita pensando en personas profundamente inmersas en ese ecosistema, por lo que para los desarrolladores que se mueven entre varios proyectos y lenguajes se requiere una cantidad considerable de energía mental para reconstruir el contexto
• Si se revisa la documentación de la función max() de Python, hay mucho conocimiento previo necesario para entender la sintaxis de definición de la función y sus conceptos, pero con cinco líneas de ejemplo puede entenderse de inmediato
• clojuredocs.org, de la comunidad de Clojure, ofrece documentación práctica mediante ejemplos aportados por usuarios y es un caso ejemplar que incluso incluye funciones relacionadas para aumentar su utilidad real
• Incluso en proyectos de software importantes, es raro que se ofrezcan los cuatro tipos de documentación, así que los desarrolladores terminan buscando tutoriales no porque necesiten guía, sino porque necesitan ejemplos

---

La importancia de los ejemplos al buscar documentación

• Cuando los desarrolladores buscan documentación, en el 95% de los casos basta con un solo ejemplo
• Sin embargo, solo en un 5% de los casos se pueden encontrar ejemplos en la fuente oficial
• La mayoría de la documentación técnica oficial está escrita teniendo como público base a personas profundamente inmersas en el ecosistema
• Muchos desarrolladores tienen que hacer malabares mentalmente entre varios "mundos" en su día a día
  • Cambian con frecuencia entre proyectos, lenguajes y frameworks
  • Esto consume una cantidad considerable de energía mental para reconstruir el contexto y entender la situación

Análisis del caso de la documentación de Python

• Ejemplo de la función max() en la documentación de Python 3
  • max(iterable, /, *, key=None): devuelve el elemento más grande
  • Después sigue una explicación en cinco párrafos cortos
• Conocimientos de Python que hay que tener para entender esta documentación
  • El significado de * en la definición de funciones
  • El significado de / en la definición de funciones
  • El concepto de "positional-only parameter separator"
  • El concepto de iterable
  • El concepto de argumentos solo por palabra clave
  • El significado general del parámetro key
• Hay que leer el texto para entender qué valores pasar y cómo invocar realmente la función

El efecto de un ejemplo simple

• Se reconoce que no se pueden omitir detalles importantes solo por mantener la concisión
• Sin embargo, muchos desarrolladores llegan a esa página simplemente para encontrar rápido cómo pasar una función de ordenamiento personalizada (key) a la función max
• Si hubiera un ejemplo como el siguiente, podrían obtener de inmediato la información que buscan

  max(4, 6) # → 6  
  max([1, 2, 3]) # → 3  
  max(['x', 'y', 'abc'], key=len) # → 'abc'  
  max([]) # ValueError: max() arg is an empty sequence  
  max([], default=5) # → 5  
  

• Los ejemplos permiten entenderlo de forma fácil e intuitiva

Un caso ejemplar de la comunidad de Clojure

• clojuredocs.org es un proyecto impulsado por la comunidad de Clojure
  • Los usuarios aportan ejemplos sobre funciones integradas
  • Es un recurso indispensable en la programación cotidiana
• Páginas de ejemplo: consultar into, spit, map y similares
• Características de los ejemplos
  • Incluyen no solo la función en cuestión, sino también funciones relacionadas
  • Aumentan la utilidad práctica y la aplicabilidad real

Los límites actuales de la documentación

• Incluso en proyectos de software importantes, es raro que se ofrezcan los cuatro tipos de documentación
  • Referencia: El sistema de documentación de Divio
• Razones por las que uno duda antes de hacer clic en el enlace "Documentation"
  • En la mayoría de los casos, se trata de referencias de API autogeneradas, concisas y difíciles de leer
• La verdadera razón por la que los desarrolladores buscan tutoriales
  • No es porque necesiten guía, sino porque necesitan ejemplos
  • Los tutoriales resultan más útiles porque incluyen ejemplos

[sonnet]

Sinceramente, creo que esto aplica sobre todo a Java y Python. También son ecosistemas donde el chauvinismo por el propio lenguaje o una cultura fuertemente aislada en términos de paradigma tienden a ser fuertes.
Tomando Python como referencia, el planteamiento encaja bien, pero cuando estudias varios lenguajes, ese 5% se siente bastante exagerado.

[kuber]

El código es la mejor documentación; vénganse a Golang~
Nosotros desarrollamos revisando el código de pruebas aunque no tengamos README

[pjtco]

Pensé que yo era el único medio tonto que no podía entender la documentación oficial jajaja
De verdad, si te ponen un ejemplo y te explican un poquito, se entiende rapidísimo.....

[nemorize]

PHP sería tanto un buen ejemplo como el peor ejemplo.

Es un buen caso porque en la documentación oficial se puede subir contenido aportado por usuarios y así revisar varios ejemplos de código,

...pero también es el peor ejemplo porque PHP tiene muchas sutiles BC en sus funciones integradas, y casi todos esos ejemplos aportados son de versiones de la época de Maricastaña, así que se mezclan cosas sutilmente distintas de cómo realmente funcionan y eso solo aumenta la confusión... jaja...

[savvykang]

En la documentación antigua de iOS o Cocoa había una sección aparte de casos de uso; ¿no sería ese el método correcto de documentación? Se necesitan ejemplos, firmas de funciones y explicaciones del comportamiento.

[aer0700]

Si antes la falta de profundidad de la documentación oficial se compensaba con Stack Overflow y búsquedas en Google, hoy parece que la compensan los LLM.

[GN⁺]

Comentarios de Hacker News

• Lo mejor del Python de antes era que abrías la documentación de una librería y encontrabas una sección donde los argumentos de las funciones y los valores de retorno estaban claramente organizados. Hoy da pena que mucha documentación de librerías de JavaScript o Python solo traiga ejemplos. Los ejemplos son buenos para construir algo rápido, pero para corregir problemas o aprender una librería, las explicaciones de los argumentos son esenciales. Está bien que los ejemplos sean un extra, pero no deberían ser todo

  • En realidad, lo que quieres son definiciones de tipos. Las definiciones de tipos hacen el trabajo de una buena documentación. Como las herramientas del sistema de tipos ya muestran mucha información directamente en el editor o el IDE, hace falta ir menos a leer la documentación. Que hoy haya más documentación centrada en ejemplos viene de ese cambio en el flujo de trabajo. Al final, no hace falta repetir en la documentación la misma información que ya te dan las herramientas de tipos. Cuando yo veo documentación, me interesa más "qué problema puede resolver esta herramienta" que los detalles de cada argumento. Los ejemplos son excelentes para mostrar esa posibilidad. Si quiero resolver un problema específico, ver un ejemplo me deja decidir rápido si esa herramienta me sirve. --- Si hay sistema de tipos, yo quiero ver primero los ejemplos. Si no hay sistema de tipos: 1) no me gusta. 2) primero quiero ver ejemplos, y después los detalles de argumentos/retornos/estructuras de datos

  • Una buena documentación necesita ambas cosas. Primero explica los detalles, y luego agrega varios ejemplos para que uno pueda comprobar lo aprendido. A veces los ejemplos bastan, pero si hay demasiadas combinaciones de opciones, es casi imposible mostrarlas todas con ejemplos. Por eso primero hay que dar una explicación de cada opción, y luego preparar ejemplos de casos lo más variados posible para que el lector pueda adaptarlos. Y hacer buena documentación es muy difícil, y hoy en día de verdad es raro verla

  • No estoy del todo de acuerdo. La documentación estilo Javadoc es documentación de programación basada en tipos y docstrings inline. Tiene que existir, pero en vez de ir a la web suele ser más eficiente ver el código mismo. Las guías con ejemplos o los QuickStart sí son indispensables. Eso baja la barrera de entrada de una librería. Viendo solo el código no es fácil entender cómo se usa una API. En el pasado me pasó con muchas librerías de Java que solo traían Javadoc y era incómodo no saber cómo usarlas

  • Creo que lo mejor son los ejemplos bien comentados. Pero no pueden reemplazar la documentación tradicional

  • Me pregunto si has considerado que otras personas pueden tener un estilo de aprendizaje distinto al tuyo. No entiendo por qué habría resistencia a que los ejemplos sean parte de la documentación. Los ejemplos reducen la fricción de cambiar de contexto en muchas situaciones

• A las páginas man de Unix también les hacen mucha falta los ejemplos. Normalmente se usan solo como referencia para gente que ya conoce bien la herramienta, así que para principiantes no ayudan nada. La buena documentación necesita ambas cosas

  • Totalmente de acuerdo. Quisiera recordarles a todos los autores de páginas man que existe la sección convencional EXAMPLE. Vale la pena revisar la documentación oficial de man(1)

  • Yo nunca he sentido ese problema. Primero me pongo a escribir algo de código y voy aprendiendo los comandos o términos, luego reviso uno por uno los códigos de error de retorno, sus causas y el significado de los parámetros. Si la documentación es completa, alcanza aunque no tenga ejemplos. En cambio, que te den solo ejemplos sin ninguna explicación sí es de lo peor. ¿Qué clase de documentación es esa donde ni siquiera puedes saber qué es un parámetro o qué significa?

  • Me gustó saber que Stack Overflow intentó algo parecido en el pasado. Operó en beta entre 2016 y 2017 con el nombre de Stack Overflow Documentation. Querían crear documentación centrada en ejemplos, pero se canceló. Aun así, el contenido que dejó la comunidad sigue disponible bajo CC BY-SA

  • Prueba con cheat.sh. Yo lo uso directamente en scripts con curl cheat.sh/"$1"

  • Siempre me sorprende la cantidad de páginas man que sí traen ejemplos. Aun así, todavía hay bastante margen para mejorarlas de manera más integral

• Los ejemplos no solo son buenos para principiantes o usuarios ocasionales. Los usuarios avanzados también necesitan documentación formal, o sea, documentación con toda la configuración de parámetros. Por ejemplo, la documentación de requests siempre hace que Google me mande a páginas llenas de ejemplos tipo Quickstart, lo cual es molesto. Todo el mundo sabe hacer un HTTP GET, pero cuesta encontrar cuáles son las otras opciones, cómo se maneja timeout o si raise_for_status ignora los 204. Se necesitan ambas cosas, pero si el tiempo del desarrollador fuera limitado, yo preferiría que primero hubiera documentación correcta. Enlace al Quickstart de requests

  • Viendo ejemplos se entiende mucho más fácil el comportamiento que con documentación estilo referencia. La gente es mala para poner nombres, ordenar conceptos y redactar documentación. Hace poco perdí horas con un parámetro que solo funcionaba bajo ciertas condiciones. Entender el código era demasiado complejo, e incluso un LLM me dijo por error que era un parámetro sin documentación. Al final, lo más eficiente fue ir armando código de ejemplo hasta encontrar el comportamiento que quería. Los ejemplos condensan varias cosas importantes y permiten validar rápido. En cambio, la documentación de API intenta cubrirlo todo, por eso es difícil de mantener y muchas veces no transmite lo esencial. Y, salvo que sea explícito, yo nunca confío en el comportamiento de una librería. Si no está claramente mostrado en el README o definido por tipos, asumo que puede cambiar en cualquier momento. Al final escribo el código de llamada de la forma más defensiva posible

  • Los ejemplos son importantes no solo para principiantes, sino para todos. Con un ejemplo de 5 segundos puedes ganar la eficiencia de una hora de lectura de documentación y experimentación. Pasa mucho con cierta documentación de git, y también con funciones que en esencia son simples pero difíciles de explicar. Aunque un desarrollador solo pudiera hacer una cosa, igual debería tener capacidad para publicar tanto ejemplos como documentación. Hay que dar ambas, salvo en casos tan obvios que de verdad no haga falta

  • De acuerdo. Una buena documentación casi debería dejar totalmente definido el comportamiento del programa, y es difícil lograr eso solo con ejemplos

  • Puedes tener ambas al mismo tiempo. Los ejemplos y la documentación técnica no son incompatibles

  • Lo de los usuarios ocasionales es exactamente a lo que me refiero. Cada vez que cambias entre proyectos, lenguajes o frameworks, recuperar el contexto y entender en qué situación estás tiene un costo mental considerable

• Habrá quien hable mal de Perl, pero la documentación de Perl de verdad ayuda. Siempre pone al frente una sección SYNOPSIS con código de ejemplo que puedes usar de inmediato. Después vienen la explicación, la referencia y más ejemplos. Ejemplos: documentación de bigrat, documentación de Archive::Tar. Al escribir documentación de proyectos, vale la pena tomar como referencia el estilo de Perl. Y ese estilo mismo está bien documentado

  • Usé Perl a inicios de los 2000 y luego por casualidad volví a usarlo en 2014, y se sintió como si todo volviera de golpe a la memoria. Tal vez sea por la perspectiva lingüística y la actitud de Larry Wall, pero deja una impresión muy fuerte. No por precisión matemática, sino porque da una fuerte sensación de "estar conversando con un amigo"

• Se necesitan ambas cosas. Los ejemplos te dan intuición inmediata y facilitan la integración, y las explicaciones de parámetros y valores de configuración ayudan a resolver problemas complejos y a entender la herramienta en su conjunto. Si falta cualquiera de las dos, de verdad es incómodo. Aunque, en librerías muy simples, los ejemplos podrían explicar prácticamente todo

  • Se necesitan tanto ejemplos como documentación de referencia. Si es posible, también conviene agregar un entorno REPL. Si puedes modificar y probar los ejemplos al instante, se compensan muchas carencias de la documentación

• El marco Diátaxis muestra muy bien que hay distintos tipos de documentación y que cada uno tiene su propósito. No se trata de cuál es "la mejor", sino de que cada una sirve para necesidades diferentes. Sitio oficial de Diátaxis

  • Esto debería estar hasta arriba. Me frustró un poco que Diátaxis apareciera solo después de tanta discusión. Yo lo veo así: los ejemplos sí son una parte central de la documentación, pero más que una "clase de documentación" independiente, son una "técnica de documentación" importante

  • ¡Exacto! Los ejemplos (o tutoriales) son una parte de la enseñanza de sistemas. No sé con certeza quién lo formuló primero, pero el enlace se parece al del autor citado al final del artículo: > "Incluso los proyectos grandes rara vez tienen los cuatro tipos de documentación. Por eso a veces da miedo hacer clic en el enlace de ‘Documentation’". A mí me gusta la documentación explicativa. Si entiendes la estructura o las razones de cómo funciona algo, luego resulta más fácil asimilar ejemplos o tutoriales. Cuando un buen redactor técnico o educador construye bien ese marco desde el inicio, el efecto es enorme. En cambio, la referencia de API suele ser más necesaria al hacer wrappers o implementaciones compatibles. De hecho, muchos proyectos empezaron con referencias de API privadas, y documentar era básicamente exponer eso hacia fuera. Ver el sistema de documentación de divio

  • El concepto de Diátaxis es excelente. Pero no es fácil aplicarlo en proyectos reales. Cada proyecto necesita proporciones distintas de documentación, y dar todas las formas en un solo sitio web no siempre es eficiente. Esa proporción también cambia con el crecimiento de la comunidad y su nivel de especialización. Ojalá hubiera un método más práctico. Documentar es una tarea difícil, y espero que algún día aparezca una solución mejor. Por ahora, la calidad depende del tiempo y la experiencia invertidos, y en general la realidad es que suele faltar de ambos

• Siento esto muy seguido con Unity y Unreal. En especial, la documentación de nodos de Unreal muchas veces solo vuelve a poner una captura del nodo y su nombre, sin enseñar en absoluto cómo se usa en la práctica. En Unity también pasa que buscas documentación para aprender a usar bien una función y resulta que casi no hay nada. Si pudiera, hasta me darían ganas de contribuir ejemplos a la documentación de Unity

  • La pésima documentación de Unreal también me ha hecho perder muchísimo tiempo. Tienen esa actitud de que "el código es la documentación", pero sus "explicaciones con captura del nodo" para Blueprint son casi de risa

  • Sobre £JOB, me pregunto si cuando la gente escribe $job lo hace pensando en un trabajo por el que ganas dinero, o si solo viene del nombre de variable. A estas alturas ya se me está tambaleando la cosmovisión

• Yo uso ImageMagick con frecuencia y siempre terminaba googleando ejemplos. Por eso junté mis notas personales en una pequeña colección de ejemplos de comandos. También agregué explicaciones detalladas de cada argumento. Creo que no basta con solo ejemplos, como en esta entrada del blog; también hace falta explicación. Todavía está en borrador, pero para tareas cotidianas como redimensionar, optimizar o trabajar con capas, ya es bastante útil. Enlace público a mis notas

• Los ejemplos de código pueden ejecutarse como pruebas unitarias para evitar que la documentación se vuelva obsoleta o se rompa. Esa es una ventaja que no existe con el lenguaje natural

  • Ahora que los LLM están avanzando, también se podría intentar, por ejemplo, verificar la exactitud de la documentación de API

• Opinión radical: si la especificación de un método concreto no puede deducirse de forma intuitiva viendo la firma y unos cuantos ejemplos representativos, entonces ese método está intentando hacer demasiadas cosas. Tampoco quiero aprender abstracciones torpes ni excepciones complejas

  • Yo no lo veo así. Los ejemplos no solo hacen falta para ese método, sino también para mostrar "cómo debe usarse junto con otros métodos". Aunque pudieras deducirlo todo a partir de la firma del método, sería fácil pasar por alto partes importantes como configuraciones faltantes, preparación previa o manejo de resultados. Por eso los ejemplos son indispensables

[howudoin]

En el ecosistema de Java y en la cultura orientada a objetos hubo especialmente muchas frases explicativas sin sentido y documentación formalista, y los frameworks del ecosistema de Python que heredaron ese ambiente también suelen tener ejemplos particularmente pobres.

Un ejemplo de documentación inútil
add(left, right) - suma el operando izquierdo y el derecho

Pero no explican lo que de verdad importa, como el tipo de dato de los parámetros, las excepciones que pueden devolverse, la forma del valor de resultado o la estructura de funcionamiento.

Si fuera una man page de C, con una explicación breve bastaría para poder usarla aunque sea infiriéndolo por el nombre de la función y de los parámetros.