Discord não é documentação
(shkspr.mobi)- O Discord é útil para ajuda em tempo real e compartilhamento de trabalho, mas é estruturalmente inadequado para substituir a documentação contínua de um projeto
- É natural que projetos open source se comuniquem onde os usuários estão reunidos, mas o Discord é, em essência, uma ferramenta voltada para conversas temporárias
- A plataforma de desenvolvimento Watchy induz os usuários a perguntar no Discord sobre informações além do guia básico de configuração, fazendo com que precisem vasculhar mensagens manualmente sem documentação de API
- Mesmo encontrando uma pergunta pela busca, é difícil entender o contexto e a relevância da resposta, e o mesmo comando ou opção pode acabar sendo interpretado de forma errada
- Se perguntas frequentes e respostas não forem reunidas em um só lugar, os usuários continuarão enfrentando atrito desnecessário no processo de aprender e usar o produto
O que o Discord ajuda e o que não pode substituir
- O Discord permite receber ajuda em tempo real sobre problemas e ver imediatamente o que outras pessoas estão criando ou onde estão travando
- A dificuldade de entrar não é muito diferente de outras ferramentas de comunicação como Slack, Matrix, Gitter e IRC
- Também é natural que projetos open source sigam o princípio de “ir onde os usuários estão”
- Usa-se a analogia de que, se todo mundo está no Facebook, não faz sentido publicar só no MySpace
- O fato de o Discord não ser open source incomoda até certo ponto, mas ele funciona bem até mesmo no Firefox
- O ponto principal é que, embora o Discord seja adequado para conversas temporárias, ele não é um substituto para documentação
A lacuna de documentação exposta no Watchy
- Ao começar a usar a plataforma de desenvolvimento Watchy, a frustração foi aumentando cada vez mais
- A forma como o conteúdo é oferecido se aproxima de “o guia básico para configuração está aqui, e o resto pergunte no Discord”
- Sem documentação de API, para encontrar a informação necessária o usuário precisa rolar manualmente por muitas mensagens
- Quando a informação fica só nas conversas do Discord, desaparece um ponto de referência estruturado como existe na documentação
O problema de contexto que a busca não resolve
- A busca do Discord dificilmente se torna uma solução real quando as pessoas não usam threads direito
- Pode até ser possível encontrar a pergunta, mas é difícil encontrar a resposta junto
- Mesmo quando se encontra uma resposta, é difícil saber se ela responde à pergunta atual ou a outra conversa
- No diálogo de exemplo, a pergunta sobre o comando fullscreen, a pergunta sobre formatação de disco e a resposta sobre a flag
-faparecem misturadas, deixando pouco claro o contexto de destino da resposta - Nessa estrutura, o mesmo comando ou opção pode ser lido com um significado completamente diferente
O atrito enfrentado por iniciantes e perguntas repetidas
- Quando a informação está espalhada pelo Discord, iniciantes acabam fazendo de novo perguntas que já apareceram muitas vezes
- Algumas pessoas reagem com irritação a esse tipo de pergunta de iniciante
- Se há muitas perguntas repetidas, uma solução mais direta é reunir as perguntas e respostas comuns em um só lugar
- Um FAQ talvez não seja a forma final correta de uma documentação abrangente, mas ao menos é necessário como organização mínima da informação
A documentação mínima que precisa existir
- Não é obrigatório seguir o Four-Document Model
- Esse modelo também tem críticas
- Ainda assim, é difícil entender por que não reunir perguntas e respostas frequentes
- Não dá para resolver uma documentação abrangente só com um FAQ, mas um projeto que nem sequer cria um FAQ deveria repensar o próprio lançamento do produto
1 comentários
Comentários do Hacker News
Há uma tendência de startups empurrarem tudo, inclusive suporte, para o Discord, e pelos motivos citados no texto isso acaba sendo uma experiência terrível do ponto de vista do usuário e do cliente
Leva tempo demais para entender a estrutura dos canais e descobrir onde postar, e também é difícil pesquisar se a solução já foi publicada. Na prática, você nem sabe quem de fato vai responder. Se você toca uma startup e está pensando em mover tudo para o Discord, deveria reconsiderar seriamente
Em vez de deixar a informação pública, encontrável pelo Google ou navegando por um portal de ajuda ou site de documentação, você faz todo mundo entrar no chat e repetir perguntas que provavelmente já foram respondidas. Isso também cria mais trabalho para você mesmo. Eu sei que muita gente faz perguntas sem ler a ajuda nem a documentação, mas se autoatendimento de suporte resolver nem que seja 10%, já vale a pena manter essa documentação atualizada
Já foi tema no Hacker News antes: “Discord is a black hole for information”
https://knockout.chat/thread/33251/1
https://news.ycombinator.com/item?id=30311982
Pelo menos no meu caso, o público é muito jovem e todo mundo quer estar no Discord. Se algum membro decente da comunidade se oferecer para moderar, aquilo praticamente funciona sozinho, com quase nenhum esforço. Na minha experiência, foi a comunidade que puxou o Discord primeiro, e a ideia de começar nem foi minha. Outras plataformas, mesmo quando eu tento empurrar, ninguém quer. Não sei por que funciona, mas simplesmente funciona
Ele dá suporte a voz, vídeo e texto, e permite interação em tempo real, interação assíncrona e interação automatizada. Também funciona na web, desktop e mobile. Dá para entender por que alguém gostaria de padronizar em uma única ferramenta para simplificar os processos de suporte e treinamento. Se conseguisse melhorar acessibilidade e usabilidade, o Discord poderia ser um grande avanço em vários aspectos. Reduzir o número de canais e dar nomes claros a eles é um bom primeiro passo, e uma mensagem curta de boas-vindas com dicas também pode ajudar
As configurações padrão de notificação são completamente bizarras: tudo fica sempre como não lido, tudo é importante, e há badges vermelhos por toda parte. Sempre que entro em um novo “servidor”, a primeira coisa é clicar com o botão direito e escolher “Suppress @everyone and @here” e “Suppress All Role Mentions”. Mesmo assim, mensagens com @everyone, @here e @role ainda aparecem destacadas em amarelo como se eu tivesse sido mencionado pessoalmente. Menções de broadcast são um recurso fadado ao abuso e nunca deveriam ter sido criadas
A caixa de entrada de mensagens também tenta ser esperta demais e ao mesmo tempo é burra demais. Ela quebrou a substituição de texto padrão do macOS e, pelo que lembro, se a mensagem começa com certos caracteres ela engole alguns deles. E, no entanto, se você digitar @username manualmente e não escolher a autocompletação que aparece, a menção não funciona
A UI para adicionar emoji de reação também é ridiculamente ruim. Ela mostra emojis recentes, depois uma quantidade interminável de emojis personalizados de todos os servidores que você nem pode usar sem assinar, e só depois aparecem os emojis Unicode
Os pop-ups, banners e tooltips promovendo assinatura paga também irritam demais. O pop-up de “novidades” idem. Se alguém usa o plano gratuito há anos e ainda não paga, já dá para supor que a chance de conversão é baixa; eu gostaria que parassem com esse upsell que agride os olhos na esperança de transformar essa pessoa em cliente pagante
Arquivos também são bloqueados com frequência demais por serem “too powerful”, e não existe opção de deixá-lo compactar do jeito que o servidor quiser. Raramente é necessário enviar imagens ou vídeos com perfeição bit a bit, e mesmo assim acontece. Algum dia penso em fazer, como próximo projeto, um mensageiro desktop multiprotocolo moderno, e o Discord vai ficar no topo da lista de serviços a serem suportados
A reação imediata do HN a certos temas está ficando cada vez mais cansativa
Uma parcela considerável das pessoas comentando agora parece nem ter lido sobre o que o texto realmente trata e só quer despejar nostalgia por antigas mailing lists e documentação meia-boca. Na melhor das hipóteses, esses documentos tinham um exemplo de código; em média, acabavam sendo só um “sumário” do código-fonte que você realmente precisava ler. Pessoalmente, eu gostaria que esses projetos tivessem um BBS além do Discord, mas é realmente muito bom simplesmente conversar com as pessoas que constroem coisas de que eu gosto e, nesse processo, virar amigo delas
No caso do Watchy, a documentação foi um bom ponto de partida: https://watchy.sqfmi.com/docs/getting-started
Há um diagrama de arquitetura, alguns exemplos de código para casos de uso comuns, e também transmite bem que este projeto é um projeto “de aventura”, com uma superfície ampla de coisas a explorar. Um dia talvez seja possível adicionar links para textos ou projetos feitos por outras pessoas, mas não sei se haverá muito desse material. É um produto bem de nicho
Há aqui alguns temas que acionam muita gente, e elas postam comentários preconcebidos sem nem ler o texto, independentemente do que a submissão realmente seja. Isso fica claro só de ver alguém criar uma conta descartável tipo “discordsucks” para comentar
Além disso, isso não são “servidores”, e sim canais
Nós também começamos a usar https://www.answeroverflow.com/ para espelhar o conteúdo do Discord na web
Dá para criar algo parecido por conta própria, mas o AnswerOverflow tem recursos bons e também lida bem com questões de consentimento. Se você vai começar um Discord agora, recomendo fortemente deixar claro desde o início que o conteúdo pode ser espelhado em outro lugar, mesmo que você não vá fazer isso imediatamente. Fazer isso depois é muito mais difícil
A solução melhor seria não usar Discord, mas, por causa do atrito das alternativas, da oposição dos colegas e do medo de fragmentar a comunidade, isso foi o melhor que conseguimos fazer. Talvez o ideal fosse não usar Discord desde o começo, mas pelo menos em algumas comunidades ele tem a vantagem de ser familiar. Também mantemos documentação “de verdade”, mas é difícil cobrir tudo, e o Discord contém informações valiosas que não ficam registradas em nenhum outro lugar
Colocando a comunicação principal em algo aberto, como XMPP MUC, Matrix Spaces, IRC, ou então em lugares como Zulip e Mattermost. Assim, mesmo que a ferramenta de chat da moda da semana mude, a base principal não fica nas mãos de uma megacorporação que pode cortar o serviço por sanções ou por uma nova barreira paga
Na minha empresa anterior, usamos Discord para suporte e foi excelente
Leva tempo para construir a comunidade no começo, mas, depois que ela existe, vira um grande ativo. As maiores vantagens são feedback de usuários em tempo real, retenção de usuários, colaboração entre usuários e ajuda vinda da própria comunidade. O Discord é conversacional, então, quando você recebe feedback sobre o produto, dá para conversar rapidamente sobre o problema exato que a pessoa está enfrentando, propor soluções e ver a reação. Quando o usuário tem acesso imediato aos desenvolvedores do produto, ele sente que sua opinião está sendo usada de forma útil, e a retenção também aumenta. Se a comunidade crescer o suficiente, os próprios usuários podem fazer brainstorming de melhorias juntos ou ajudar usuários novos, reduzindo o tempo que os desenvolvedores gastam com suporte
Pessoalmente, acho a crítica de que “não é indexado” um pouco engraçada. Com que frequência você já pesquisou um erro obscuro e acabou chegando a uma mailing list? Normalmente, os e-mails indexados não têm resposta e, mesmo quando têm, muitas vezes não resolvem o problema. Vasculhar histórico de conversa não é um meio eficiente de documentação. Nós usamos o feedback da comunidade como sinal para identificar lacunas na documentação e atualizamos os docs de acordo. Se 10 usuários perguntaram sobre o recurso X esta semana, isso significa que a documentação precisa ser atualizada
Hoje existem threads, mas todo mundo precisa usá-las. Se você encontra alguém que fez a mesma pergunta e não há resposta, não dá para saber se realmente não houve resposta ou se ela foi dada fora da thread, 1000 mensagens abaixo. Sem threading, é um desastre
Já aconteceu muitas vezes comigo de pesquisar um erro obscuro e chegar a uma mailing list, mas fóruns eram melhores. Em Discord ou Slack, quase nunca consegui resposta e, quando consegui, raramente foi uma boa resposta. Se a pergunta é empurrada para cima, ninguém mais vê, e, mesmo quando alguém responde, muitas vezes é um iniciante entusiasmado que não entendeu o problema
Antigamente eu postava bastante em fóruns e mostrava o problema com precisão usando exemplos de reprodução bem validados. Também fazia aquela coisa de “uma pergunta, uma resposta”, passando pela primeira ou segunda página de perguntas sem resposta e deixando uma resposta quando eu sabia algo
Quase todos os canais de “suporte” em Discord ou Slack foram péssimos. É uma forma de a empresa reduzir o suporte deslocando a expectativa para ignorar os usuários. O Drone(CI) também fez isso recentemente, e o canal no Slack estava cheio apenas de perguntas de usuários
Acho que a verdadeira razão de Discord etc. serem populares é o baixo custo de esforço. Ninguém espera que você traga um exemplo completo e acabado; como é uma conversa, basta jogar uma pergunta meio pronta e esperar que alguém vá conduzindo e pegando na sua mão. O preço disso é perder pessoas que querem participar de uma comunidade que exige esforço, em vez de um espaço cheio de emoji e meme
A própria web virou um espaço quase impossível de pesquisar. Por causa de spam de SEO, da piora na qualidade da busca do Google, da tendência de tudo ir para dentro de jardins murados e do movimento de aumentar os preços de APIs e reter dados para enfrentar os LLMs
Em geral, acho que a morte da web pesquisável está empurrando as pessoas para o Discord. Não é tanto culpa dos desenvolvedores individuais; para eles, como foi dito, há ganho líquido. O que precisamos é de uma “ozempic web”. Uma web que mantenha a escala de 2023, mas seja mais leve, indexável, sem muros e com menos preenchimento inútil e monetização caça-cliques. Até lá, por mais que se critique os jogadores, o próprio jogo está torto
Mas isso é viés de seleção. As conversas das quais o dono participou naturalmente vão bem. Então, o que acontece com as outras? Se uma pergunta sem resposta é soterrada por outras conversas três horas depois, a empresa nem vê essa pergunta. A empresa não consegue ver o que não viu, e é assim que surge o viés de seleção
O Discord tira informações desses lugares abertos. Às vezes, inclusive, a gente descobre um projeto por meio dessas respostas. Dito isso, eu me interesso por FLOSS mais do que por startups de código proprietário, então o foco principal do cliente pode ser uma questão diferente
Primeiro, houve sucesso em integrar o Discord ao processo de documentação. Quando chega feedback sobre X, a documentação é atualizada para cobrir X. Já o Eden diz que muitos projetos respondem X no Discord e depois não atualizam a documentação
Segundo, a equipe responde rapidamente às mensagens no Discord. Muitas equipes enrolam ou simplesmente não respondem
Chat não é documentação
Quando bato em algum bloqueio, primeiro dou uma olhada rápida na implementação, mas isso não ajuda muito quando a base de código não é familiar. Fui conferir a documentação e só havia um link dizendo “Participe da comunidade no Discord”. Então abro o Discord, instalo a atualização, faço a autenticação de dois fatores personalizada baseada em e-mail, aceito os termos alterados, fecho o banner do Nitro, concordo com as regras do servidor e entro no #general. Faço uma pergunta tentando dar o máximo de contexto possível, mas não recebo resposta. No fim, ligo o depurador e sigo a biblioteca ou o framework linha por linha para descobrir o que está acontecendo. Depois de criar uma cópia editável, adicionar logs e tentar algumas alterações, horas depois descubro que X não oferece suporte a Y, ou que é preciso codificar o valor em Base 47 ou Latin 1 antes de passá-lo adiante. E então, 3 dias depois, à 1 da manhã, recebo no Discord uma resposta com tom de desdém mandando eu ver uma conversa de 2 semanas antes de eu ter entrado
O chat transfere em grande parte para o usuário o peso de identificar o problema por conta própria e de os próprios usuários se darem suporte entre si. Especialmente no mundo do trabalho assíncrono, ele não pode ser um substituto para a documentação. Parece adequado para trabalho assíncrono porque dá para responder de forma assíncrona, mas não é, porque não dá para desbloquear um impedimento de forma assíncrona
Trabalhando com Django por cerca de 8 dos últimos 12 anos, quase a única vez em que usei um depurador no código do Django foi ao encontrar vulnerabilidades de segurança e precisar ter certeza de detalhes de nível muito baixo. Em comparação, em um mês fazendo um projeto de hobby por cerca de 5 dias com um projeto que recomendava Discord em vez de documentação, tive que usar o depurador 3 vezes só para descobrir o que estava acontecendo
Há, de fato, uma solução cultural e de processo muito útil aqui: transformar cuidadosamente as perguntas do Discord em atualizações da documentação
Se isso for feito, o Discord pode se tornar um acelerador poderoso para melhorar a qualidade da documentação do projeto. Mas isso exige o mesmo nível de disciplina
Se eu preciso fazer o meu trabalho, mas tenho que passar o dia inteiro monitorando Slack, Discord e Mattermost, então não estou fazendo o meu trabalho. Se o meu trabalho for suporte, aí é uma exceção. Como desenvolvedores tendem a ser ingênuos, ter opiniões fortes e querer agradar os outros, este é mais um caso de desenvolvimento de software assumindo também o suporte, que é outra área do negócio. Na época do ágil, assumimos o gerenciamento de projetos; na época do DevOps, assumimos a administração de sistemas. Pode variar conforme a situação
Parece o tipo de coisa que alguém já deve ter implementado, mas da última vez que procurei não encontrei nada
Como usuário de produto, não quero entrar na comunidade de pessoas aleatórias e me deixar arrastar para conversas improdutivas
Também não quero ficar dando refresh em um chat quase síncrono, nem perder informação importante porque fiquei um dia fora. Gostaria que as empresas respeitassem o meu tempo e a minha atenção
A busca do Discord é surpreendentemente ruim. Os usuários reclamam disso há anos, mas nada melhora
Só isso já o desqualifica como documentação
Se um usuário sai do servidor, deixa de ser possível pesquisar especificamente o que ele postou. Mesmo quando o usuário ainda está no servidor, a busca do Discord nem sempre parece conhecer todos os usuários atuais, então pode ser difícil encontrar o que aquela pessoa postou. Se você pesquisar algo com muitos resultados e tentar voltar para a primeira página, ou seja, para os resultados mais antigos, tudo quebra. Por exemplo, em alguns servidores eu não consigo pular para a minha primeira mensagem. Também não dá para pesquisar dentro de uma thread específica. O próprio modo como a busca por texto funciona já me irritou no passado, mas agora não consigo encontrar um bom exemplo do que exatamente era o problema
Nessas empresas, engajamento — isto é, perda de tempo — tende a ser visto como uma qualidade desejável
Pelo mesmo motivo, o Slack também não é documentação
Atualmente estou trabalhando para melhorar a documentação da empresa inteira. Somos uma startup antiga em um setor com um tempo de chegada ao mercado muito longo, e no último trimestre liderei dois projetos nos quais gastamos semanas respondendo perguntas sobre código antigo. Às vezes, o autor original já tinha saído da empresa e não havia documentação alguma; às vezes, o autor original ainda estava na empresa, mas literalmente já não se lembrava de ter escrito aquele código, e também não havia documentação. Em todos os casos, as pessoas diziam que havia alguma conversa no Slack, em algum lugar, explicando tudo. Não, não havia. Todo projeto e toda aplicação precisam de um documento de design antes, e de um manual do usuário depois, e isso realmente precisa ser mantido
Fico confuso com o entusiasmo quase estranho da comunidade mais ampla pelo Discord
Como outra pessoa disse, na essência é um IRC com multimídia. Por que fazem tanta propaganda? Mesmo aceitando a ideia bastante controversa de “obter suporte no Discord”, o produto em si não tem nada de especial. Só é um pouco melhor do que produtos parecidos que já existiam. Isso sem nem entrar nas preocupações muito reais sobre como os dados dos usuários serão usados no futuro
E muitos usuários nunca usaram IRC. Também pesa o fato de existir um app com o mesmo nome do serviço. Então vira uma “coisa” única, como Instagram ou TikTok. É até surpreendente quantas pessoas nunca pensaram no fato de que o app do reddit e o serviço/site do reddit são coisas separadas. A comunidade de TI mais ampla também ainda é bem próxima de um nicho pequeno, e nós esquecemos disso com frequência
Tirando o Slack, o Discord criou o produto de chat e voz baseado em navegador voltado ao consumidor com a maior qualidade. É bem projetado, estável e tem uma interface de usuário simples na maior parte do tempo
O IRC e várias alternativas frequentemente citadas muitas vezes travam já nessa primeira etapa, mesmo só com chat de texto puro, quanto mais com multimídia. Os concorrentes que entenderam isso falharam na implementação ou chegaram tarde demais. As preocupações com privacidade têm prioridade baixa demais para os usuários para que consigam derrubar a vantagem de pioneiro do Discord
Só isso já basta. Mas em vários aspectos ele também é muito melhor que o IRC. Claro, dá para rodar você mesmo um bouncer de IRC para a Libera numa “conta shell” ou numa microinstância da AWS sempre ligada, mas quem, além dos mais nerds, vai querer fazer isso? Ainda assim, quando você entra num canal novo, não consegue ver mensagens antigas, e mesmo com bot de histórico ou página de arquivo, tudo é desajeitado. Sem falar no ritual do NickServ em cada rede. E também não há a boa multimídia que hoje a maioria dos usuários espera como parte normal da cultura de comunicação
Some a isso uma UI decente, prévias de link em que o remetente sabe exatamente o que o destinatário vai ver, formatação de mensagens ao estilo Markdown, metadados suficientes para encadear respostas, reações com emoji compactas que não transformam o canal em spam e conferências de voz e vídeo que funcionam bem sem configuração extra. Tirando a busca e a UI de busca, entre as alternativas só o Zulip talvez tenha uma UI tão boa
Eu costumava usar IRC todos os dias, até operava um bouncer com arquivamento e administrava canais de comunidade, mas já não me importo mais. Em um período em que fiquei ocupado e doente, meu nome de usuário registrado no NickServ expirou e isso até quebrou a administração dos canais, o que também me desanimou. Quando todo mundo saiu do Freenode para a Libera, eu simplesmente parei de usar IRC
Ao mesmo tempo, concordo fortemente com a crítica ao modo como os projetos usam o Discord de uma forma que continuam produzindo documentação útil, mas na prática a perdem. É preciso reconhecer que o Discord criou um produto polido, de alta qualidade, com efeitos de rede compreensíveis. Mas é uma pena que seja difícil para os projetos arquivar seus canais publicamente e torná-los pesquisáveis, e também é uma pena que não seja nem uma rede aberta nem um produto open source. O fato de a busca e a UI de busca serem ruins também entra nisso
Considerando que a maioria dos projetos que vejo usando Discord, inclusive muitos comerciais, é open source, ainda existe a possibilidade de o Matrix acabar substituindo isso algum dia, a menos que o Discord abra a rede de alguma forma. Mas há muito atrito: projetos existentes não conseguem migrar o histórico de chat nem os usuários, e projetos novos precisam encontrar os usuários onde eles já estão, isto é, em redes como Discord, Slack e Telegram