Discord no es documentación
(shkspr.mobi)- Discord es útil para recibir ayuda en tiempo real y compartir trabajo, pero estructuralmente no sirve para reemplazar la documentación sostenida de un proyecto
- Es natural que los proyectos de código abierto se comuniquen donde están sus usuarios, pero Discord es, por naturaleza, una herramienta pensada para conversaciones efímeras
- La plataforma de desarrollo Watchy lleva a preguntar en Discord cualquier cosa más allá de la guía básica de configuración, obligando a los usuarios a revisar mensajes por su cuenta ante la falta de documentación de la API
- Aunque se encuentren preguntas con la búsqueda, es difícil entender el contexto y la relevancia de las respuestas, por lo que un mismo comando u opción puede interpretarse de forma equivocada
- Si las preguntas frecuentes y sus respuestas no se reúnen en un solo lugar, los usuarios seguirán enfrentando fricción innecesaria al aprender y usar el producto
Qué ayuda a hacer Discord y qué no puede reemplazar
- Discord permite recibir ayuda en tiempo real sobre un problema y ver de inmediato qué están creando otros o en qué se traban
- La dificultad para unirse no es muy distinta de la de otras herramientas de comunicación como Slack, Matrix, Gitter o IRC
- También es natural que los proyectos de código abierto sigan el principio de “ir a donde están los usuarios”
- Se usa la analogía de que, si todos están en Facebook, no tiene sentido publicar solo en MySpace
- El hecho de que Discord no sea open source genera cierta incomodidad, pero funciona bien incluso al abrirse desde Firefox
- El punto clave es que, aunque Discord sirve para conversaciones pasajeras, no es un sustituto de la documentación
El vacío de documentación que se hizo evidente en Watchy
- Al empezar con la plataforma de desarrollo Watchy, la frustración fue creciendo cada vez más
- La forma en que se presenta se parece a: “aquí está la guía básica para configurarlo; para lo demás, pregunta en Discord”
- Sin documentación de la API, encontrar la información necesaria obliga a los usuarios a desplazarse manualmente por una gran cantidad de mensajes
- Cuando la información queda solo dentro de conversaciones en Discord, desaparece un punto de referencia estructurado como el que ofrece la documentación
El problema del contexto que no se resuelve con la búsqueda
- La búsqueda en Discord difícilmente funciona como una solución real si la gente no usa bien los hilos
- Puede que encuentres la pregunta, pero no la respuesta correspondiente
- Incluso si encuentras una respuesta, cuesta saber si responde a la pregunta actual o a otra conversación distinta
- En el ejemplo de conversación, se mezclan una pregunta sobre el comando fullscreen, una pregunta sobre formato de disco y una respuesta sobre el flag
-f, dejando poco claro el contexto al que responde - En una estructura así, el mismo comando u opción puede leerse con un significado completamente distinto
La fricción para principiantes y las preguntas repetidas
- Si la información está dispersa en Discord, los principiantes terminan haciendo de nuevo preguntas que ya aparecieron muchas veces
- Algunas personas reaccionan con fastidio ante este tipo de preguntas de principiantes
- Si hay muchas preguntas repetidas, una solución más directa es reunir las preguntas comunes y sus respuestas en un solo lugar
- Puede que un FAQ no sea la forma final correcta de una documentación integral, pero al menos hace falta como mínimo de organización de la información
La documentación mínima que al menos debería reunirse
- No es obligatorio seguir el Four-Document Model
- Este modelo también tiene críticas
- Aun así, cuesta entender que no se reúnan al menos las preguntas frecuentes con sus respuestas
- Un FAQ no puede resolver por sí solo una documentación completa, pero un proyecto que ni siquiera crea un FAQ debería reconsiderar publicar el producto
1 comentarios
Comentarios de Hacker News
Hay una tendencia entre las startups a meterlo todo en Discord, incluido el soporte, y por las razones que menciona el artículo eso termina siendo una experiencia terrible desde el punto de vista del usuario o cliente
Se pierde demasiado tiempo entendiendo la estructura de canales y buscando dónde publicar algo, y también es difícil buscar si ya se compartió una solución. Ni siquiera sabes quién te va a responder realmente. Si diriges una startup y estás pensando mover todo a Discord, deberías reconsiderarlo seriamente
En vez de dejar la información pública para que se encuentre con Google o navegando un portal de ayuda o un sitio de documentación, haces que todos entren al chat y vuelvan a preguntar cosas que muy probablemente ya fueron respondidas. También te generas más trabajo a ti mismo. Sé que mucha gente pregunta sin leer la ayuda o la documentación, pero si aunque sea un 10% se resuelve con soporte de autoservicio, vale la pena mantener esos documentos actualizados
Es un tema que ya se había tratado antes en Hacker News: “Discord is a black hole for information”
https://knockout.chat/thread/33251/1
https://news.ycombinator.com/item?id=30311982
Al menos en mi caso, la audiencia es muy joven y todos quieren estar en Discord. Si un miembro decente de la comunidad se ofrece a moderar, en la práctica casi funciona solo. Por mi experiencia, Discord fue algo que la propia comunidad empujó primero, y ni siquiera fue idea mía arrancar con eso. Otras plataformas, aunque yo las impulse, nadie las quiere. No sé por qué funciona, pero simplemente funciona bien
Soporta voz, video y texto, y permite interacción en tiempo real, diferida y automatizada. También funciona en web, escritorio y móvil. Se entiende querer estandarizar en una sola herramienta para simplificar procesos de soporte y capacitación. Si pudiera mejorar en accesibilidad y usabilidad, Discord podría ser un gran avance en muchos sentidos. Reducir la cantidad de canales y ponerles nombres claros sería un buen primer paso, y también podría ayudar un mensaje corto de bienvenida con algunos consejos
La configuración predeterminada de notificaciones es completamente absurda: todo aparece siempre como no leído, todo es importante y hay insignias rojas por todas partes. Cada vez que entras a un “servidor” nuevo, primero tienes que hacer clic derecho y elegir “suprimir @everyone y @here” y “suprimir menciones de roles”. Aun así, los mensajes con @everyone, @here y @role siguen apareciendo resaltados en amarillo como si te hubieran mencionado personalmente. Las menciones masivas son una función destinada al abuso y nunca debieron existir
El cuadro para escribir mensajes también pretende ser demasiado inteligente y al mismo tiempo es demasiado tonto. Arruinó la sustitución de texto predeterminada de macOS y, si mal no recuerdo, se come algunos caracteres cuando el mensaje empieza con ciertos símbolos. Pero luego, si escribes @username manualmente y no eliges la autocompletación que aparece, la mención no funciona
La interfaz para agregar reacciones con emoji también es ridículamente mala. Primero muestra los emojis recientes, luego una lista interminable de emojis personalizados de todos los servidores que ni siquiera puedes usar si no estás suscrito, y solo después aparecen los emojis Unicode
También son muy molestos los popups, banners y tooltips promocionando la suscripción de pago. Lo mismo con los popups de “novedades”. Si alguien lleva años usando el nivel gratuito y no ha pagado, ya deberías asumir que la posibilidad de conversión es baja y dejar de castigarle la vista con intentos de upsell con la esperanza de volverlo cliente de pago
Los archivos también se bloquean demasiado seguido por ser “too powerful”, y no hay opción para dejar que el servidor los comprima como quiera. Rara vez hace falta enviar imágenes o video con perfección bit a bit. Algún día pienso hacer un mensajero de escritorio multiprotocolo moderno como próximo proyecto, y Discord va a estar al principio de la lista de servicios compatibles
La reacción instantánea de HN ante ciertos temas me está cansando cada vez más
Muchos de los que están comentando ahora ni siquiera leyeron de qué trata el texto y más bien parecen querer desahogar nostalgia por las viejas listas de correo y por documentación a medio hacer. En el mejor de los casos, esos documentos traían un ejemplo de código, y en promedio no pasaban de ser una “tabla de contenido” del código fuente que de todos modos había que leer. Personalmente me gustaría que estos proyectos tuvieran también un BBS además de Discord, pero poder simplemente hablar con la gente que hace cosas que me interesan y hacer amistad en el proceso está muy bien
En el caso de Watchy, la documentación era un buen punto de partida: https://watchy.sqfmi.com/docs/getting-started
Tiene un diagrama de arquitectura, algunos ejemplos de código para casos de uso comunes y además transmite bastante bien que este proyecto es uno de tipo “aventura”, con una superficie amplia de cosas por explorar. Tal vez algún día se puedan agregar enlaces a textos o proyectos hechos por otras personas, pero no sé si exista tanto material. Es un producto bastante de nicho
Aquí hay varios temas que disparan a mucha gente, y sin importar cuál sea el envío real, publican comentarios preconcebidos sin siquiera leerlo. Basta con ver a alguien comentar desde una cuenta temporal tipo “discordsucks”
Además, esas no son “servidores”, son canales
Nosotros también empezamos a usar https://www.answeroverflow.com/ para reflejar el contenido de Discord en la web
También podríamos haber hecho algo parecido por nuestra cuenta, pero AnswerOverflow tiene funciones bastante decentes y además maneja bien los temas de consentimiento. Si van a arrancar una comunidad nueva en Discord, recomiendo mucho dejar claro desde el principio que el contenido puede reflejarse en otro lugar, incluso si no van a hacerlo de inmediato. Más adelante se vuelve mucho más difícil
La solución mejor sería no usar Discord, pero por la fricción de las alternativas, la resistencia de los compañeros y el miedo a que la comunidad se disperse, para nosotros esta fue la mejor opción. Puede que lo ideal haya sido no usar Discord desde el principio, pero al menos para algunas comunidades tiene la ventaja de ser familiar. También mantenemos documentación “de verdad”, pero es difícil meterlo todo ahí, y en Discord hay contenido valioso que no queda registrado en otros lados
Poner la comunicación principal en algo abierto como XMPP MUC, Matrix Spaces, IRC, o en lugares como Zulip o Mattermost. Así, aunque cambie la herramienta de chat de moda de esta semana, la base principal no queda operada por una megacorporación que puede cortar el servicio por una sanción o por una nueva barrera de pago
En mi empresa anterior usamos Discord para soporte y fue excelente
Lleva tiempo construir la comunidad al inicio, pero una vez armada se vuelve un activo enorme. La mayor ventaja es la retroalimentación de usuarios en tiempo real, la retención de usuarios, la colaboración entre usuarios y la ayuda impulsada por la comunidad. Discord es conversacional, así que cuando recibes feedback sobre el producto puedes hablar rápido sobre qué problema exacto están teniendo, proponer soluciones y ver la reacción. Si los usuarios pueden acceder de inmediato a los desarrolladores del producto, sienten que su opinión sirve para algo y también mejora la retención. Cuando la comunidad crece lo suficiente, los usuarios pueden hacer lluvia de ideas juntos sobre mejoras o ayudar a usuarios nuevos, reduciendo el tiempo que los desarrolladores dedican al soporte
Personalmente, me parece un poco ridícula la crítica de que “no se indexa”. ¿Qué tan seguido has buscado un error raro y terminado en una lista de correo? Normalmente los correos indexados no tienen respuesta y, aun cuando la tienen, muchas veces no resuelven el problema. Revisar historiales de conversación no es un medio eficiente de documentación. Nosotros usamos el feedback de la comunidad como señal para detectar qué falta en la documentación y la actualizamos en consecuencia. Si esta semana 10 usuarios preguntaron por la función X, eso significa que hay que actualizar la documentación
Ahora hay hilos, sí, pero solo si todo el mundo los usa. Si encontraste a alguien que hizo la misma pregunta pero no tiene respuesta, no hay forma de saber si de verdad no la tuvo o si la respondieron fuera del hilo 1000 mensajes más abajo. Sin hilos es un desastre
Muchas veces he buscado errores raros y he terminado en listas de correo, aunque los foros eran mejores. En Discord o Slack casi nunca conseguí respuesta y, cuando la conseguí, rara vez fue una buena respuesta. Si tu pregunta se va hacia arriba, nadie la ve, y aunque alguien responda, muchas veces es un principiante entusiasta que no entendió el problema
Antes publicaba mucho en foros y mostraba el problema con ejemplos reproducibles bien verificados. También revisaba la primera o segunda página de preguntas sin responder con la lógica de “si haces una pregunta, responde una” y dejaba respuesta si sabía algo
Casi todos los canales de “soporte” en Discord o Slack eran pésimos. Es una forma en que las empresas bajan el soporte moviendo la expectativa hacia ignorar a los usuarios. Drone(CI) también hizo eso hace poco, y su canal de Slack estaba lleno solo de preguntas de usuarios
Creo que la razón real por la que Discord y similares son populares es el bajo costo de esfuerzo. No se espera que llegues con un ejemplo terminado; como es una conversación, puedes lanzar una pregunta a medio hacer y esperar a que alguien te vaya guiando y te lleve de la mano. El costo de eso es perder a la gente que sí quiere participar en una comunidad que exige esfuerzo, en lugar de un espacio lleno de emojis y memes
La web misma se ha vuelto un espacio casi imposible de buscar. Por el spam de SEO, la caída en la calidad de las búsquedas de Google, el encierro de todo detrás de muros, y la tendencia a subir los precios de las API y acaparar datos para defenderse de los LLM
En general, creo que la muerte de la web buscable empuja la migración hacia Discord. Más que culpa de los desarrolladores individuales, para ellos sí hay una ganancia neta, como se dijo. Lo que hace falta es una “ozempic web”: una web del tamaño de 2023 pero más liviana, indexable, sin muros y con menos relleno inútil y monetización basada en captar atención. Hasta que eso exista, por más que critiques a los jugadores, el juego mismo está torcido
Pero eso es sesgo de selección. Las conversaciones en las que participa el dueño, por supuesto, salen bien. Entonces, ¿qué pasa con las demás? Si una pregunta que nadie respondió queda enterrada tres horas después bajo otras conversaciones, la empresa ni siquiera la ve. La empresa no puede ver lo que no vio, y ahí aparece el sesgo de selección
Discord le quita información a esos espacios abiertos. A veces incluso descubro proyectos gracias a ese tipo de respuestas. Dicho eso, a mí me interesa más el FLOSS que las startups de código privativo, así que el enfoque principal del cliente puede ser un problema distinto
Primero, tuvieron éxito en integrar Discord al proceso de documentación. Si recibían feedback sobre X, actualizaban la documentación para cubrir X. En cambio, Eden dice que muchos proyectos responden sobre X en Discord y luego no actualizan la documentación
Segundo, el equipo responde rápido a los mensajes de Discord. Muchos equipos se demoran muchísimo o no responden en absoluto
El chat no es documentación
Cuando me topo con un bloqueo, primero reviso por encima la implementación, pero como no conozco bien el codebase no me sirve de mucho. Revisé la documentación y no había más que un enlace de “Únete a la comunidad de Discord”. Entonces abrí Discord, instalé una actualización, hice una autenticación de dos factores personalizada basada en correo electrónico, acepté los términos actualizados, cerré el banner de Nitro, acepté las reglas del servidor y entré a #general. Publico una pregunta con todo el contexto posible, pero no hay respuesta. Al final enciendo el depurador y sigo la librería o el framework línea por línea hasta entender qué está pasando. Después de crear una copia editable, agregar logging e intentar algunos cambios, horas más tarde descubro que X no soporta Y, o que hay que codificar el valor en Base 47 o Latin 1 antes de pasarlo. Y luego, tres días después, a la 1 de la mañana, recibo en Discord una respuesta que parece desentendida diciéndome que vea una conversación de dos semanas antes de que yo me uniera
El chat traslada en gran medida al usuario la carga de descubrir el problema por su cuenta y de que los propios usuarios se den soporte entre sí. En especial en el mundo del trabajo asíncrono, no puede sustituir a la documentación. Parece bueno para el trabajo asíncrono porque permite responder de forma asíncrona, pero no lo es porque no permite desbloquearse de manera asíncrona
Durante unos 8 de los últimos 12 años he trabajado con Django, y casi la única vez que usé un depurador sobre código de Django fue cuando encontré una vulnerabilidad de seguridad y necesitaba confirmar detalles de muy bajo nivel. En cambio, con un proyecto que recomendaba Discord en lugar de documentación, dediqué unos 5 días de un mes a un proyecto personal y tuve que usar el depurador hasta 3 veces solo para averiguar qué estaba pasando
Aquí sí hay una solución cultural y de proceso realmente útil. Consiste en convertir meticulosamente las preguntas de Discord en actualizaciones de la documentación
Si se hace así, Discord puede convertirse en un potente acelerador para mejorar la calidad de la documentación del proyecto. Pero requiere ese mismo nivel de disciplina
Si tengo que hacer mi trabajo, pero debo pasarme todo el día vigilando Slack, Discord o Mattermost, entonces no puedo hacer mi trabajo. Si mi trabajo es soporte, eso es una excepción. Como los desarrolladores suelen ser ingenuos, tener opiniones fuertes y querer complacer a los demás, este es otro caso de cómo el desarrollo de software termina apropiándose de otra área del negocio: soporte. En la época ágil se hizo cargo de la gestión de proyectos, y con DevOps se hizo cargo de la administración de sistemas. Puede variar según el contexto
Parece que alguien ya debería haberlo implementado, pero la última vez que busqué no encontré nada
Como usuario de un producto, no quiero entrar a una comunidad de personas al azar y verme arrastrado a conversaciones improductivas
Tampoco quiero estar refrescando un chat casi sincrónico, ni perderme información importante por haberme desconectado un día. Ojalá las empresas respetaran mi tiempo y mi atención
La búsqueda de Discord es sorprendentemente pésima. Los usuarios llevan años quejándose, pero no mejora
Solo por eso ya no califica como documentación
Si un usuario abandona el servidor, ya no puedes buscar de forma específica lo que publicó. Incluso si el usuario sigue en el servidor, a veces parece que la búsqueda de Discord no conoce siempre a todos los usuarios actuales, así que puede ser difícil encontrar lo que esa persona publicó. Si buscas algo con muchos resultados e intentas volver a la primera página, es decir, al resultado más antiguo, se rompe. Por ejemplo, en algunos servidores no puedo saltar a mi primer mensaje. Tampoco se puede buscar dentro de un hilo específico. El propio funcionamiento de la búsqueda de texto también me molestaba antes, pero ahora no encuentro un buen ejemplo de qué era exactamente lo que estaba mal
En ese tipo de empresas, el engagement —o sea, perder el tiempo— tiende a considerarse una cualidad deseable
Por la misma razón, Slack tampoco es documentación
Ahora mismo estoy trabajando en mejorar la documentación de toda la empresa. Somos una startup antigua en un sector donde llegar al mercado toma muchísimo tiempo, y el trimestre pasado lideré dos proyectos en los que pasamos semanas respondiendo preguntas sobre código antiguo. A veces el autor original ya había dejado la empresa y no había ninguna documentación; otras veces el autor original seguía en la empresa, pero literalmente ya no recordaba haber escrito ese código, y tampoco había documentación. Cada vez, la gente decía que en algún lado había conversaciones de Slack que lo explicaban todo. No, no las hay. Todo proyecto y toda aplicación necesitan un documento de diseño antes, un manual de usuario después, y ambos tienen que mantenerse de verdad
Me confunde lo extrañamente entusiasmada que está la comunidad más amplia con Discord
Como dijo otra persona, en esencia es IRC con multimedia. ¿Por qué lo promocionan tanto? Incluso si aceptamos la muy controvertida idea de “recibir soporte en Discord”, el producto en sí no tiene nada de especial. Apenas es un poco mejor que productos similares que ya existían. Aparte están las preocupaciones muy reales sobre cómo se usarán los datos de los usuarios en el futuro
Y muchos usuarios nunca han usado IRC. También pesa mucho que exista una app con el mismo nombre que el servicio. Así se convierte en una sola “cosa”, como Instagram o TikTok. Sorprende bastante cuánta gente nunca ha pensado que la app de reddit y el servicio/sitio de reddit son cosas distintas. La comunidad IT más amplia también sigue siendo más bien un nicho pequeño, y a menudo se nos olvida
Fuera de Slack, Discord hizo el producto de mayor calidad entre las apps de chat y voz basadas en navegador orientadas al consumidor. Está bien diseñado, es estable y tiene una interfaz de usuario mayormente simple
IRC y muchas de las alternativas que suelen mencionarse a menudo se quedan atoradas en ese primer paso incluso solo con chat de texto puro, ni hablar de multimedia. Los competidores que sí entendieron eso fallaron en la implementación o llegaron demasiado tarde. Las preocupaciones por la privacidad tienen una prioridad demasiado baja para los usuarios como para que sea probable que derriben la ventaja del primero en moverse de Discord
Solo con eso ya basta. Pero además en muchos aspectos es mucho mejor que IRC. Claro, puedes correr tú mismo un bouncer de IRC para Libera en una “cuenta shell” o en una microinstancia de AWS siempre encendida, pero salvo la gente más clavada, ¿quién querría hacer eso? Aun así, no puedes ver mensajes antiguos cuando entras a un canal nuevo, y aunque haya bots de historial o páginas de archivo, todo se siente tosco. Tampoco hay que olvidar el ritual de NickServ en cada red. Y además falta la buena multimedia que la mayoría de los usuarios hoy espera como parte de una cultura de comunicación normal
A eso súmale una UI decente, vistas previas de enlaces donde el remitente sabe exactamente lo que verá el receptor, formato de mensajes tipo Markdown, suficiente metadato para enlazar respuestas, reacciones con emoji compactas que no convierten los canales en spam, y conferencias de voz y video que funcionan bien sin configuración extra. Salvo la búsqueda y la UI de búsqueda, la interfaz también es buena frente a las alternativas, excepto quizá Zulip
Antes usaba IRC todos los días, incluso operé un bouncer con archivado y administré canales de comunidad, pero ya no me importa. Entre que estuve ocupado y enfermo por un tiempo, expiró el nombre de usuario de NickServ que había registrado y hasta se rompió la administración de canales, y eso también me quitó las ganas. Cuando todos se fueron de Freenode a Libera, simplemente dejé de usar IRC
Al mismo tiempo, estoy muy de acuerdo con las críticas a la manera en que los proyectos usan Discord de forma que siguen produciendo documentación útil pero en la práctica la pierden. Hay que reconocer que Discord hizo un producto pulido, de buena calidad y con efectos de red comprensibles. Pero es una lástima que a los proyectos les cueste tanto hacer que sus canales sean archivables públicamente y buscables, y también que no sea ni una red abierta ni un producto de código abierto. Lo mismo con lo mala que es la búsqueda y su UI
Considerando que la mayoría de los proyectos que veo usar Discord, especialmente si incluimos proyectos comerciales, son de código abierto, todavía existe la posibilidad de que Matrix lo reemplace algún día, a menos que Discord abra la red de alguna manera. Pero hay mucha fricción: los proyectos existentes no pueden mover el historial del chat ni a sus usuarios, y los proyectos nuevos tienen que encontrarse con los usuarios donde ya están, es decir, en redes como Discord, Slack o Telegram