Como uma equipa de docs corrigiu as páginas certas ao perguntar na própria página

Um projeto open-source tem boa documentação e um problema real: o guia de instalação está subtilmente errado. Um passo mudou há duas versões, e agora recém-chegados ficam presos no mesmo ponto. As pessoas notam — há resmungos nas redes sociais e algumas perguntas confusas no chat da comunidade — mas os mantenedores não conseguem agir sobre nada disso, porque nenhuma das queixas diz **qual página**. 'A vossa documentação está desatualizada' é uma sensação, não um reporte de bug. Então o passo errado fica lá durante meses, a afastar silenciosamente cada novo utilizador que tenta começar. A documentação vive ou morre por este ciclo: um leitor bate numa passagem confusa ou errada, diz aos mantenedores exatamente onde, e os mantenedores corrigem. Parta o 'exatamente onde' e todo o ciclo estagna. ## O problema: feedback sem localização é ruído Os leitores estão dispostos a ajudar. Dizem-lhe felizmente que uma página é confusa. O que não vão fazer é a arqueologia necessária para tornar essa ajuda acionável — copiar o URL, encontrar o canal de contacto certo, descrever o problema, e notar qual secção e qual versão. Isso são muitos passos para alguém que está a tentar aprender a sua ferramenta, não a auditar a sua documentação. Por isso o feedback que chega é despido daquilo que o torna útil: a localização. Um mantenedor a ler 'os docs de API estão errados' tem centenas de páginas e nenhuma ideia de onde procurar. Uma issue do GitHub ajuda, mas pede a um leitor casual que tenha uma conta, entenda o template de issues, e mude de contexto para fora dos docs — atrito que filtra a maior parte do feedback de passagem, que é exatamente o feedback que apanha erros pequenos e de alto impacto. O resultado é um estranho desequilíbrio: muitos leitores notam problemas, quase nenhum é reportado numa forma que consiga corrigir. ## A solução: um link 'Reportar um problema' por página Coloque um pequeno link **Reportar um problema com esta página** no rodapé de cada página de docs. É um link `mailto:`, e o seu truque é pré-preencher o caminho da página atual no assunto e no corpo. O leitor clica, o email abre com a localização já capturada, e tudo o que adiciona é o que estava mal. Como os docs são normalmente construídos a partir de um template ou um gerador de sites estáticos, pode injetar o caminho automaticamente. Num site com template, coloque a variável de página diretamente no link: ```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 um problema com esta página </a> ``` Ou defina-o com uma linha de script para funcionar em qualquer página sem templating: ```html <a id="docs-issue" href="#">Reportar um problema com 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> ``` O gerador deste site produz o link codificado; o script só troca pelo caminho ao vivo. Agora cada reporte nomeia a página exata no assunto, e um mantenedor pode saltar direto para o ficheiro fonte. ## Porque na-página bate um issue tracker aqui Um issue tracker é a casa certa para uma correção, mas uma porta pobre para feedback. Exige uma conta, uma mudança de contexto, e familiaridade com o seu processo — barreiras que afastam o leitor casual que acabou de detetar um typo numa amostra de código. O link `mailto:` encontra os leitores onde a confusão acontece: na página, num clique, sem conta. Captura a cauda longa de pequenas correções que nunca sobreviveria à viagem para um tracker. Os dois funcionam bem juntos. Os reportes chegam por email, pré-etiquetados com a página; um mantenedor faz triagem e abre issues no tracker só para os que valem a pena rastrear. Tem o baixo atrito do email à entrada e o rigor de um tracker à saída. ## Configuração 1. Escolha uma caixa de docs como `docs@` que os mantenedores vigiam. 2. No gerador, defina o destinatário, um assunto de 'Docs issue: [caminho da página]', e um corpo que peça o que está mal e o que ajudaria. 3. Adicione o link ao rodapé do template da página, injetando o caminho com a variável de página do seu gerador ou o pequeno script acima. 4. Encaminhe correio pela tag de assunto 'Docs issue:' para que reportes caiam num sítio. 5. Feche o ciclo: quando corrige uma página reportada, uma resposta de uma linha ao leitor transforma um reporte de bug em boa vontade. ## O que poupa A primeira poupança é **tempo de mantenedor gasto a localizar problemas**. Quando cada reporte nomeia a página, salta o trabalho de detetive e vai direto à correção. Um reporte que era um inacionável 'algo está errado nalgum sítio' torna-se numa edição de dois minutos. A segunda é **menos utilizadores presos**. Erros de documentação compõem-se: um passo errado de instalação não falha uma vez, falha para cada recém-chegado até alguém o corrigir. Encurtar o tempo entre 'um leitor nota' e 'um mantenedor sabe exatamente onde' significa que cada passagem má afasta muito menos pessoas. Para uma ferramenta que cresce por adoção, desbloquear recém-chegados é crescimento. A terceira é **volume e honestidade de feedback**. Como reportar leva um clique e sem conta, mais leitores o fazem — incluindo os que nunca abririam uma issue de tracker. Ouve sobre os pequenos erros embaraçosos que erodem confiança, e ouve enquanto ainda importam. ## Como o tornar ainda melhor - Preencha automaticamente a **versão do doc ou o commit** ao lado do caminho, para poder ver se um reporte é anterior a uma reescrita recente. - Adicione o link a **páginas 404** nos seus docs, onde uma página em falta é ela própria sinal útil. - Mantenha o endereço **ofuscado** para que bots não o colham de milhares de páginas públicas. - Ofereça uma alternativa visível para leitores sem app de email padrão, como um endereço em texto ou um link ao tracker. ## Pontos-chave - Feedback de docs sem localização é ruído; os leitores raramente fazem o trabalho de anexar uma. - Um link `mailto:` 'Reportar um problema' por página pré-preenche o caminho exato, para que cada reporte seja acionável. - Email na-página captura as correções casuais que um tracker filtra, e depois alimenta o tracker para correções reais. - Poupa tempo de mantenedor, desbloqueia recém-chegados mais rápido, e faz emergir os pequenos erros que silenciosamente custam confiança. Construa o seu próprio link de feedback de docs no [gerador](/#generator), ou copie a configuração abaixo.