Cómo un equipo de documentación corrigió las páginas correctas preguntando en la página misma

Un proyecto open-source tiene buena documentación y un problema real: la guía de instalación está sutilmente equivocada. Un paso cambió hace dos versiones, y ahora los recién llegados se atascan en el mismo punto. La gente lo nota —hay quejas en redes sociales y un par de preguntas confusas en el chat de la comunidad— pero los mantenedores no pueden actuar al respecto, porque ninguna de las quejas dice **qué página**. "Su documentación está desactualizada" es un sentimiento, no un reporte de bug. Así que el paso incorrecto se queda ahí por meses, alejando silenciosamente a cada nuevo usuario que intenta empezar. La documentación vive o muere por este ciclo: un lector se topa con un pasaje confuso o erróneo, dice a los mantenedores exactamente dónde, y los mantenedores lo arreglan. Rompe el "exactamente dónde" y todo el ciclo se estanca. ## El problema: el feedback sin ubicación es ruido Los lectores están dispuestos a ayudar. Te dirán con gusto que una página es confusa. Lo que no harán es la arqueología necesaria para hacer que esa ayuda sea procesable: copiar la URL, encontrar el canal de contacto adecuado, describir el problema y notar qué sección y qué versión. Eso son muchos pasos para alguien que está intentando aprender tu herramienta, no auditar tu documentación. Por lo tanto, el feedback que llega está desprovisto de lo único que lo hace útil: la ubicación. Un mantenedor leyendo "los docs de la API están mal" tiene cientos de páginas y ninguna idea de dónde buscar. Un issue de GitHub ayuda, pero le pide a un lector casual que tenga una cuenta, entienda tu plantilla de issues y cambie completamente de contexto fuera de los docs; fricción que filtra la mayor parte del feedback de paso, que es exactamente el feedback que atrapa errores pequeños de alto impacto. El resultado es un extraño desequilibrio: muchos lectores notan problemas, casi ninguno es reportado de una forma que puedas arreglar. ## La solución: un enlace de "Reportar un problema" por página Coloca un pequeño enlace de **Reportar un problema con esta página** en el pie de página de cada página de documentación. Es un enlace `mailto:`, y su truco es que autocompleta la ruta de la página actual en el asunto y el cuerpo. El lector hace clic, su correo se abre con la ubicación ya capturada, y todo lo que añaden es lo que estaba mal. Como los docs generalmente se construyen a partir de una plantilla o un generador de sitios estáticos, puedes inyectar la ruta automáticamente. En un sitio con plantillas, coloca la variable de página directamente en el enlace: ```html <a href="mailto:docs@yourproject.dev?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Reportar un problema con esta página </a> ``` O configúralo con una línea de script para que funcione en cualquier página sin plantillas: ```html <a id="docs-issue" href="#">Reportar un problema con esta página</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:docs@yourproject.dev' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` El generador en este sitio produce el enlace codificado; el script solo intercambia la ruta en vivo. Ahora cada reporte nombra la página exacta en su asunto, y un mantenedor puede saltar directo al archivo fuente. ## Por qué en-la-página supera a un issue tracker para esto Un issue tracker es el hogar adecuado para una corrección, pero una mala puerta de entrada para el feedback. Exige una cuenta, un cambio de contexto y familiaridad con tu proceso: barreras que alejan al lector casual que acaba de detectar un error tipográfico en un ejemplo de código. El enlace `mailto:` encuentra a los lectores donde la confusión ocurre realmente: en la página, en un clic, sin cuenta. Captura la larga cola de pequeñas correcciones que nunca sobrevivirían al viaje hacia un tracker. Ambos funcionan bien juntos. Los reportes llegan por correo electrónico, pre-etiquetados con la página; un mantenedor hace triaje de ellos y abre issues en el tracker solo para los que vale la pena rastrear. Obtienes la baja fricción del correo electrónico en la entrada y el rigor de un tracker en la salida. ## Configuración 1. Elige una bandeja de entrada de docs como `docs@` que los mantenedores vigilen. 2. En el generador, define el destinatario, un asunto de "Docs issue: [ruta de la página]", y un cuerpo que pregunte qué está mal y qué ayudaría. 3. Añade el enlace al pie de la plantilla de tu página, inyectando la ruta con la variable de página de tu generador o el pequeño script de arriba. 4. Enruta el correo entrante por la etiqueta de asunto "Docs issue:" para que los reportes caigan en un solo lugar. 5. Cierra el ciclo: cuando arregles una página reportada, una respuesta de una línea al lector convierte un reporte de bug en buena voluntad. ## Lo que ahorra El primer ahorro es el **tiempo del mantenedor invertido en localizar problemas**. Cuando cada reporte nombra la página, te saltas el trabajo de detective y vas directo a la solución. Un reporte que solía ser un inaccionable "algo está mal en algún lugar" se convierte en una edición de dos minutos. El segundo es **menos usuarios atascados**. Los errores de documentación se componen: un paso de instalación incorrecto no falla una vez, falla para cada recién llegado hasta que alguien lo arregla. Acortar el tiempo desde que "un lector lo nota" hasta que "un mantenedor sabe exactamente dónde" significa que cada mal pasaje aleja a mucha menos gente. Para una herramienta que crece por adopción, desbloquear a los recién llegados es crecimiento. El tercero es **el volumen y la honestidad del feedback**. Como reportar toma un clic y ninguna cuenta, más lectores lo hacen, incluyendo aquellos que nunca abrirían un issue en el tracker. Escuchas sobre los errores pequeños y embarazosos que erosionan la confianza, y escuchas sobre ellos mientras aún importan. ## Hazlo aún mejor - Autocompleta la **versión del doc o commit** junto a la ruta, para que puedas saber si un reporte es anterior a una reescritura reciente. - Añade el enlace a las **páginas 404** en tus docs, donde una página faltante es en sí misma una señal útil. - Mantén la dirección **ofuscada** para que los bots no la recolecten de miles de páginas públicas. - Ofrece una alternativa visible para los lectores sin una aplicación de correo predeterminada, como una dirección en texto plano o un enlace a un tracker. ## Puntos clave - El feedback de docs sin una ubicación es ruido; los lectores rara vez hacen el trabajo de adjuntar una. - Un enlace `mailto:` de "Reportar un problema" por página autocompleta la ruta exacta, por lo que cada reporte es procesable. - El correo en-la-página captura las correcciones casuales que un tracker filtra, y luego alimenta al tracker para soluciones reales. - Ahorra tiempo al mantenedor, desbloquea a los recién llegados más rápido y saca a la luz los pequeños errores que silenciosamente cuestan confianza. Construye tu propio enlace de feedback de docs en el [generador](/#generator), o copia la configuración a continuación.