Como eu, um desenvolvedor iniciante, leio o tutorial que você (desenvolvedor) escreveu para mim

• Texto que retrata com humor a confusão e as barreiras que iniciantes enfrentam ao ler tutoriais técnicos escritos por desenvolvedores
• Os termos técnicos e siglas usados com frequência por desenvolvedores soam para iniciantes como um “idioma alienígena”, totalmente sem contexto
• Etapas de instalação, caminhos de arquivos e comandos de terminal em tutoriais costumam ser complexos demais ou omitidos, o que dificulta a compreensão
• A autora aponta que explicações óbvias do ponto de vista de desenvolvedores se tornam obstáculos que exigem horas de busca e tentativa e erro para iniciantes
• Este texto relembra aos desenvolvedores que escrevem tutoriais que é preciso explicar de forma mais gentil e clara a partir da perspectiva de quem está começando

---

Contexto do texto e problema levantado

• A autora descreve, como iniciante não desenvolvedora, a experiência de ler tutoriais escritos por desenvolvedores
• O texto satiriza a situação em que termos técnicos e nomes de ferramentas aparecem sem que iniciantes tenham a menor ideia do que significam
• Ex.: usa nomes técnicos fictícios como Hoobijag, Snarfus e Shamrock portal para enfatizar como tudo parece complexo aos olhos de quem está começando

---

Tradução do texto original

“Oi! Eu sou desenvolvedor. Minha experiência relevante é a seguinte: programo com Hoobijag e às vezes também uso jabbernocks, e claro, também faço ABCDE++++ (mas nunca ABCDE+/^+, né, isso seria ridículo? haha!) e gosto de trabalhar com Shoobababoo e, de vez em quando, também mexo com kleptomitrons. Acabei indo parar em código relacionado a Shoobaboo na Company[1], e isso me levou ao Snarfus. Então, vamos começar!

Sobre este tutorial

Comecei a fazer uma coisa bem simples[2] no Snarfus, e quanto mais eu usava, mais via o potencial! O chromus é meio emaranhado, mas na verdade é muito versátil. Então comecei a argylar pintafore com quagmire em vez de hoobastank! Eu sei, uma loucura. Mas até que funcionou de certa forma, e na verdade foi bem divertido… até eu topar com um grande obstáculo: o fisterfunk simplesmente não conversa com o shamrock portal, nem envia beep-boops para o Snarfus! Claro, você sabe o que isso significa[3] — agora o hoob-túnel inteiro está entupido de gramelions. Inaceitável.

Eu quase desisti, mas aí percebi: se você conectar o backside Snarfus stagnator ao backside shamrock Klingon troglodyte emulater, funciona! Tudo começou a fazer beep-boops e ding-dongs, e finalmente cheguei ao assunto real do tutorial. E aí consegui fazer uma coisa muito simples do jeito que eu queria! Bem legal, né[4].

Então, aqui está como configurar:

1. No terminal, digite ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas
2. Agora vá para folder/hidden/deep/in/the/file/system/surprise!.file e copie o conteúdo do arquivo. Se não estiver lá, talvez esteja em library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file
3. Volte ao terminal, cole o conteúdo do arquivo e digite 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][[]()()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!
4. Boop![5]
5. Abra o Snarfus e envie o arquivo que você acabou de criar
6. Só por diversão, se quiser desativar o sham do chronostatiomatrix — execute —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][]. É opcional
7. Pronto!

Me conta como foi. Também estou curiosa para saber se alguém usa esse método com GewGawGamma ou ometer2.7.”

---

Explicação das notas

1. Parece ser uma empresa famosa, mas eu não conheço
2. Não é nada simples
3. Não faço ideia do que isso significa
4. É legal, mas eu não entendi. Ainda assim, que bom que você conseguiu
5. As três primeiras etapas provavelmente vão exigir umas 7 horas e 193 pesquisas. Mas quando você chega ao Boop!, é uma sensação e tanto

Encerramento

• “Isso foi escrito só por diversão. Meus sinceros agradecimentos a todas as pessoas que compartilham conhecimento e escrevem tutoriais.”

[GN⁺]

Comentários no Hacker News

• Recomendo fortemente a abordagem de pedir para alguém com o mínimo de conhecimento possível seguir a documentação e observar em silêncio ao lado. Nesse momento, não ajude em nada, apenas observe. Assim, dá para descobrir vários problemas: onde o usuário trava, pontos tão familiares para o autor que ele nem percebe mais, configurações que ficaram faltando etc. Se a pessoa conseguir atingir o objetivo sem muito estresse, a documentação passou no teste. Caso contrário, é preciso registrar sem deixar escapar nenhum ponto de falha, melhorar cada um deles e testar de novo com outra pessoa. Já usei documentação de empresas grandes como a FAANG que não passaria nesse critério. Sou muito grato por nossa organização manter um padrão alto. Quando a documentação é feita assim, diminuem reuniões repetitivas, pedidos de suporte e chamadas de vídeo, e os usuários passam a conseguir resolver problemas por conta própria

  • Tenho essa experiência com frequência ao usar a documentação da Apple. Muitas definições no texto apenas repetem o nome do termo e seguem em frente sem explicar nada; precisavam ser bem mais concretas
  • A regra de “não falar, só observar” parece fácil, mas na prática muita gente não se segura e começa a explicar ou dar dicas. Já vi até pegarem no mouse. Para evitar esse tipo de reação humana, ajuda ter um moderador neutro separado, enquanto o autor/desenvolvedor apenas observa. Mas é importante aprender a técnica de “apenas observar” e, se quiser se aprofundar, recomendo pesquisar sobre o "think-aloud protocol"
  • A maioria dos documentos de onboarding de equipes em empresas tem uma qualidade horrível, e isso já serve como prévia da carga real de trabalho. Nas três equipes mais recentes em que entrei, a documentação quase não existia ou estava desatualizada, então eu precisava caçar as pessoas certas para conseguir os acessos necessários ou informações sobre o pipeline de deploy. Nesse processo, eu acabava escrevendo nova documentação, mas ela ficava obsoleta assim que um sistema ou permissão mudava, num ciclo sem fim. Só uma equipe configurou todo o ambiente necessário em dois dias, e essa experiência foi excelente. Agora estou em um novo time de devex tentando melhorar o próprio ambiente de documentação
  • Fazer onboarding lendo documentação ruim de setup realmente parece multiplicar o estresse por 10. Sempre incentivei que o primeiro ajuste de um novo funcionário fosse corrigir os problemas que ele encontrou. Como ele ainda não tem contexto nenhum, acaba sendo o melhor revisor possível
  • Nossa organização também usa esse mesmo fluxo. Fazemos alguém menos experiente seguir a documentação e depois incentivamos todos a melhorá-la continuamente. Isso porque iniciantes enxergam bem os “pontos cegos” que aparecem com muitos anos de experiência. Pela minha experiência, aprendi que gerenciar a confiança do usuário também é muito importante. Por isso, ao orientar etapas como “execute este comando no shell”, por padrão oferecemos algumas seções recolhidas (por exemplo: exemplo de saída bem-sucedida, avisos que podem ser ignorados, lista de erros possíveis e como tratá-los, explicação de comandos complexos etc.). Algumas etapas chegam a ter uma página inteira de explicação, mas durante o onboarding esse nível de detalhe ajuda muito na prática

• O título do post no blog era “Eu, como não desenvolvedor, lendo um tutorial escrito por você, desenvolvedor”, mas no HN ele foi mudado para “Eu, como desenvolvedor iniciante...”. Não desenvolvedor e desenvolvedor iniciante são coisas totalmente diferentes. Por exemplo, para alguém de RH ou sem qualquer formação na área, até termos internos ou conceitos podem ser completamente desconhecidos. Nesse caso, se o desenvolvedor escreveu uma explicação totalmente desconectada, merece mesmo ser criticado. Já um desenvolvedor iniciante, mesmo que ache difícil, pode pesquisar por conta própria termos e conceitos novos e, com o tempo, até atualizar a documentação para o próximo iniciante que chegar

  • Para constar, o texto foi enviado com o título “não desenvolvedor”, mas no meio do caminho virou “desenvolvedor iniciante”. A autora é uma blogueira não técnica e, para lidar com websites ou CSS, deve ter precisado consultar vários documentos técnicos. Talvez tivesse sido mais apropriado discutir publicação de sites e ausência de documentação para não especialistas, mas tudo bem a comunidade do HN levar a conversa para outra direção
  • Essa distinção é muito importante. A autora Annie diz que trabalha com “conteúdo/documentação” e que tem CSS como hobby, então ela entra na categoria de “desenvolvedor amador não profissional”. Acho que é um grupo que só vai crescer. Ao escrever tutoriais que incluam iniciantes/não desenvolvedores, basta acrescentar uma explicação bem simples até em frases como cd ~/.snarfus (crie a pasta se ela não existir). Eu mesmo, no passado, ao instalar Debian, fui muito ajudado por pequenas explicações assim
  • O site que mais me impressionou quando comecei a aprender programação foi o “FromZero”. Era voltado a não desenvolvedores e explicava passo a passo desde instalar a IDE até abrir o console. E, quando apareciam termos desconhecidos, tranquilizava dizendo algo como “vamos tratar disso mais tarde, então não se preocupe com isso agora”. Foi excelente. Claro, escrever documentação exige muito tempo e esforço, então às vezes alguma explicação já é melhor do que nenhuma. Acho que documentação para desenvolvedores iniciantes deveria ser escrita com o mesmo cuidado que se teria com não desenvolvedores
  • Algumas pessoas afirmam que, se tudo não for explicado de forma extremamente fácil, isso é gatekeeping, e ignoram o fato de que, mesmo sentindo dificuldade, ninguém consegue entender qualquer assunto imediatamente sem conhecimento prévio
  • Se é um tutorial para desenvolvedores iniciantes e não um texto voltado a profissionais experientes, é estranho esperar que ele explique em detalhes todos os conceitos como “Hoobijag” ou “shamrock portal”. Na prática, todos nós aprendemos no começo pesquisando termos desconhecidos no Google

• A maior parte dos tutoriais não é para não desenvolvedores; é mais parecida com troca de informação entre colegas desenvolvedores, ocupando uma posição semelhante à de artigos acadêmicos voltados a um grupo específico de conhecimento. E isso não é necessariamente ruim. Na verdade, também facilita revisitar anotações que eu mesmo deixei no passado. É por isso que existem cursos e materiais separados para iniciantes. Se todo tutorial tivesse de começar sempre com 30 mil caracteres de contexto e explicação de base, ninguém chegaria ao fim. Por outro lado, mesmo colocando mais contexto, para alguém ainda pode continuar parecendo insuficiente

  • Meu filho, de 17 anos, tem muito interesse em programação, e recentemente ensinei a ele os conceitos de public/private/internal/static mais recursão. Agora estou curioso para ver qual será a reação dele na próxima vez
  • Não concordo com a afirmação de que “a maioria dos tutoriais não é para não desenvolvedores”. Quero deixar claro que o próprio título deste tutorial indicava essa intenção. É muito importante existir essa voz dizendo que, quando alguém sofre tentando instalar um projeto open source, até um guia de instalação bem básico deveria ser fácil o suficiente para um iniciante seguir. Se pular um passo pequeno, em uma área pouco familiar dá para perder horas nisso
  • Também não acho ruim escrever documentação de forma mais acolhedora para todos. Uma boa documentação é útil não só para iniciantes, mas também para desenvolvedores. Se não há documentação acessível, é apenas porque ninguém quer fazer esse pequeno esforço extra. E, diferente de artigos acadêmicos, a documentação de desenvolvedor muitas vezes sofre por ser concisa demais ou por ser escrita sem considerar quem vai ler. No fim, vira um material inútil para qualquer um que não seja especialista. Isso é um fracasso
  • Concordo que precisamos de documentação que construa contexto passo a passo para iniciantes. Só que, hoje em dia, ao melhorar DX, muita gente tem priorizado apenas o que é “fácil”, sacrificando logs úteis, mensagens de erro pesquisáveis e outras coisas valiosas que já existiam. Assim, acaba-se mirando só nos iniciantes e deixando a experiência pior para usuários antigos
  • Hoje em dia, muitos tutoriais parecem mais textos para registrar no currículo “eu contribuí para o projeto X”. Seria melhor se o autor tentasse seguir o próprio tutorial de novo três meses depois; aí certamente perceberia com clareza o que ficou faltando, e isso levaria a uma grande melhoria

• Muitos technical writers não percebem de verdade a “maldição do conhecimento”. Já tive experiência liderando uma guilda de WoW. Quarenta pessoas se reuniam ao mesmo tempo para entrar em masmorras e cooperar contra vários chefes, e um único erro pequeno podia matar o grupo inteiro. Por isso, todos se juntavam no Teamspeak e a estratégia era explicada com bastante antecedência. A maior lição dali foi: “assuma que a outra pessoa não sabe do que você está falando” e “repita até o que já foi dito uma vez”. Quase ninguém interrompe para perguntar quando está com dúvida, então o hábito de ficar se perguntando “que termo eu estou usando?” e “essa pessoa pode não conhecer este conceito” e complementar a explicação teve um efeito enorme. Essa experiência de comunicação se aplica integralmente à comunicação técnica, e internalizar esse esforço para superar a “maldição do conhecimento” aumenta muito a compreensão dos outros

  • Numa antiga guilda de raid, vendo um líder de guilda de 18 anos juntar adultos de vários fusos horários e coordenar bem loot, estratégia e agenda, pensei: “esse garoto deveria ser contratado como gerente imediatamente”
  • Qualquer pessoa que já administrou raid de 40 pessoas adquire habilidades de altíssimo nível como gerente de projetos. É literalmente conduzir um bando de gatos dispersos com eficiência

• Muitos sites de projetos e READMEs no GitHub são escritos com a atitude de que “quem está lendo isto já sabe tudo”. Quando leio documentação, eu gostaria de ver mais cuidado com pontos como: por que essa ferramenta é necessária, que problema ela resolve, como se diferencia de outras parecidas, se ainda é usada atualmente, e se oferece material suficiente para eu mesmo avaliar prós e contras. Basta investir cinco minutos pensando “o que até um iniciante gostaria de saber?” e escrever isso; a acessibilidade sobe muito. É realmente uma pena quando um projeto feito ao longo de vários anos acaba repetidamente fazendo o usuário desistir por puro incômodo, sem nem perceber que ele tentou. E também é importante entender bem o papel de cada tipo de documentação. https://diataxis.fr/ é um ótimo ponto de partida

  • Na área de ROS (software de robótica), sempre me estressei muito com a pobreza dos READMEs. Muitas vezes, além do nome do projeto, não há pista nenhuma, então fica difícil até descobrir para que serve. Não é só um problema de open source; tive exatamente a mesma experiência no trabalho, e parece que eu sou a única pessoa que se dispõe a acrescentar explicações ao README. Sinto até saudade da época do monorepo
  • Entendo que são ferramentas feitas com carinho e trabalho por desenvolvedores, mas só cuidar melhor da documentação já diminuiria bastante a barreira de entrada. E, se a documentação de outros componentes da stack também for difícil, a curva de aprendizado fica exponencialmente mais íngreme
  • Houve até um projeto postado no HN, tempos atrás, que nem dizia o que era

• O mais importante ao escrever documentação é definir com clareza o nível de conhecimento do público-alvo. Tanto faz se a linha de base for alta ou baixa, mas, se você se afastar demais dela, alguns leitores inevitavelmente vão se incomodar. Nessas horas, dá para escolher a desculpa ou buscar a solução. Na prática, com IA, Google, livros etc., hoje qualquer coisa pode ser pesquisada na hora. Se você quer saber o que é “Shoobababoo” ou por que usar “quagmire”, basta procurar. Claro, o ideal é que a documentação seja o mais autossuficiente possível e não dependa de informação externa, mas o mundo nem sempre oferece esse nível de gentileza

  • Por isso é ainda pior aquela tendência em vários guias de configuração de começar por “agora dê duplo clique no arquivo exe e aperte next”. Definir bem a linha de base do guia é realmente importante
  • Eu escrevo principalmente documentação para sistemas internos sensíveis e, às vezes, deixo explicitado no começo algo como: “este guia assume que você já sabe usar x, y e z; caso contrário, você não deve fazer esta tarefa”. O acesso já é restrito, mas, no caso improvável de alguém pouco familiarizado precisar usar isso num cenário de DR, por exemplo, ainda deixo de propósito essa fronteira de “se você não entende nem isso, não faça de jeito nenhum”

• O princípio que sempre enfatizei ao longo de muitos anos de mentoria é: “o melhor é compartilhar o que você sabe”. Se você sabe algo, explique. Mesmo que a pessoa já soubesse, no máximo você reforçou a certeza dela; se ela não sabia, ajudou muito. Às vezes reclamam que isso é prolixo demais, mas, quando digo “isso foi escrito pensando na possibilidade de um novato, um cliente ou um gerente ler”, a maioria entende. Esse princípio vale para desenvolvimento, relatórios, gestão de pessoas e qualquer outra área

  • Claro, há também pessoas que detestam profundamente receber explicação sobre algo que já sabem. Se a proporção sinal-ruído ficar ruim demais, isso pode até atrapalhar a comunicação em si
  • Vejo algo parecido ao ensinar sinuca para meu filho. Uma cultura em que as pessoas baixam a guarda e compartilham dicas livremente ajuda muito no crescimento do time. Na mentoria, em vez de dar logo a resposta, conduzir a pessoa por perguntas para que ela chegue sozinha à descoberta gera evolução real quando ela entende por conta própria
  • Explicar tudo para todo mundo pode ser interpretado como “mansplaining” ou como alguém querendo posar de sabe-tudo, o que politicamente pode ser ameaçador. Em algumas empresas, às vezes é mais seguro simplesmente responder apenas quando as pessoas fazem perguntas

• Recentemente tentei fazer deploy de um app do Gitlab no Kubernetes da DigitalOcean e precisei implementar de 3 a 4 ferramentas de terceiros sem qualquer explicação do que faziam. Também tive de descobrir sozinho que nomes ou caminhos digitar na linha de comando. Não havia explicação de qual era o padrão nem do que precisava corresponder ao quê. Mesmo tendo bastante experiência com Docker, a documentação dessas ferramentas era tão pouco amigável que teria sido melhor não haver documentação nenhuma

• O principal motivo de eu ter parado de escrever livros e criado um site de tutoriais foi poder usar várias ferramentas interativas para tornar os tutoriais mais acessíveis para mais pessoas (<abbr> e outros recursos). Mesmo assim, ainda me frustra que o conteúdo da web de hoje continue preso às limitações do papel. Existem clique, hover, recolhimento de seções, vídeo, reação do usuário e tantos outros recursos, mas ainda assim só vemos enormes paredes de texto. Até o próprio OP usa aquele estilo de clicar na nota de rodapé e ser levado para o fim da página, o que passa a sensação de não aproveitar de verdade o potencial da web

  • Acabei de começar a atualizar meu blog e agradeceria recomendações de sites que façam isso bem, com tutoriais interativos bem construídos

• Na verdade, a maior parte dos tutoriais, em vez de ser para não desenvolvedores ou para desenvolvedores, acaba sendo apenas “texto longo desnecessário” que no fim pula uma ou duas etapas realmente importantes. Acho que a principal causa é como é difícil escrever como se estivesse explicando para outra pessoa. Se você não tirar da própria cabeça o que sabe e colocar isso por escrito, o leitor nunca vai descobrir sozinho. Em vez de “tutorial”, seria melhor escrever no estilo de “cookbook”, que funciona melhor na prática e evita que o material fique inútil depois de uma atualização de versão

  • Ironicamente, hoje em dia muitas receitas online têm ainda mais enrolação inútil do que blogs de não desenvolvedores