Toss divulga guia de technical writing
(technical-writing.dev)Princípios fundamentais para escrever uma boa documentação técnica
1. Definir o tipo de documentação
Dependendo do objetivo da documentação, a forma mais eficaz de escrever muda
- Documentação voltada ao aprendizado: quando a pessoa entra em contato com uma nova tecnologia ou ferramenta pela primeira vez, com o objetivo de entender o fluxo geral
- Documentação de solução de problemas: quando já existe conhecimento prévio, com o objetivo de resolver um problema específico
- Documentação de referência: quando a pessoa já sabe como usar, mas quer confirmar o uso de uma função específica ou de uma API
- Documentação explicativa: com o objetivo de entender em detalhes conceitos, princípios e conhecimentos de base
2. Criar uma estrutura de informação
Entender um conhecimento novo exige esforço, mas estruturar a informação pode reduzir esse esforço
- Tratar de apenas um assunto por página
- Entregar valor primeiro
- Escrever títulos eficazes
- Não deixar de fora a visão geral
- Tornar o conteúdo previsível
3. Refinar as frases
Ao aumentar a clareza das frases, o leitor consegue entender o conteúdo com mais facilidade. Quando detalhes importantes são expressos em frases difíceis de compreender, a capacidade de comunicação cai bastante
- Deixar claro o sujeito da frase
- Manter apenas as informações necessárias
- Escrever de forma concreta
- Usar expressões naturais em coreano
- Escrever com consistência
6 comentários
Não existe algum lugar que reúna sites como esses feitos pela Toss?
A forma em
-yoé difícil de se acostumar.É isso mesmo.
Muito bom, especialmente a parte sobre refinamento de frases; acho que vou tentar criar algo com few-shot usando GPTs.
Acho que textos assim são bons. Como diretrizes como essas poderiam se transformar na era dos LLMs?
Que projeto incrível ^^