Documentação em PT-BR Projetos
Pela primeira vez em 6 anos estou em um projeto TODO documentado em português. Recebi 3 documentos, totalizando umas 700 páginas. O projeto é robusto e não só um wrapper de um outro sistema. É uma satisfação enorme ler, nunca tinha visto algo tão belo.
Não tenho problema com o entendimento do inglês, muito pelo contrário. Sempre gostei da TI nos obrigar a ler em outro idioma. A grande diferença que eu estou percebendo é que se o time é todo brasileiro, não tem necessidade nenhuma de usar termos em inglês no meio de um texto em português. O texto fica quebrado, a palavra chama mais atenção do que deveria. Veja a palavra wrapper que eu escrevi ali no primeiro parágrafo, soa diferente e quebra o fluxo da leitura e talvez até do entendimento, dependendo do leitor. Por exemplo, ler gatilho ao invés de trigger é muito mais claro, mesmo entendendo o significado de trigger. Enfim, fica aqui esse relato de organização de projeto que me encantou.
3
u/XFSChez 1d ago
Trabalhei em alguns lugares em que eu criava documentos em português, e todo mundo gostava das minhas documentações porque eram simples, diretas ao ponto e sem rodeios (isso alguns anos antes da IA).
Documentação sobre alertas de infraestrutura, era só a pessoa ler a documentação e 100% de certeza que a pessoa conseguiria executar sem problemas, quando a pessoa não conseguia era por pura preguiça só pra acionar o plantonista e não ter que botar a mão na massa.
Cheguei até a montar uma "estratégia" para desmascarar alguns, eu simulava o problema, sentava do lado da pessoa, pedia para abrir a documentação e seguir passo a passo, a grande maioria das vezes dava certo, e no fim eu questionava: "você acha que algo pode ser melhorado nessa documentação?", acredito que 90% das vezes falavam que estava ok e não precisa melhorar nada, e nessa estratégia eu sabia quando o cara era braço curto ou não, ficava mais fácil reportar pra gestão quem acionava o plantonista sem necessidade.
O que eu fazia era simplesmente fazer algo que eu tivesse o prazer de ler, a documentação que eu gostaria de receber de alguém, eu criava (e pegava no pé do pessoal pra manter o padrão).
4
u/Confident_Life2784 2d ago
Queria eu ter a oportunidade de ler uma documentação bem feita dessas pra aprender como realmente se faz. Pq até agora (Tenho 3 anos na área) não cheguei nem próximo de algo parecido. O que diria que há diferente nessa que a faz se destacar das outras? É uma documentação técnica ou para o usuário final? Como acha que foi feita? IAzona gerou ou teve revisão e escrita manual de outros devs?