Redação Técnica
Compartilhar:
Essas perguntas foram mostradas apenas aos entrevistados envolvidos com redação técnica.
12% de todos os participantes disseram que estavam envolvidos em redação técnica. Dentre eles, apenas 10% tinham cargos oficiais como redatores técnicos.
Isso significa que na pesquisa da JetBrains sobre o Estado do Ecossistema dos Desenvolvedores de 2023, 90% das pessoas que escrevem documentação não se intitulam redatores técnicos. Isso levanta questões sobre a colaboração entre equipes, a qualidade e consistência da documentação e o papel dos redatores técnicos.
Daniele Procida
Diretor de Engenharia, Canonical
A documentação não abrange apenas redação técnica ou o que é redigido. Ela dá forma ao relacionamento de um usuário com um produto e também afeta como seus criadores o entendem. Todas as partes interessadas em um produto devem se dedicar a pensar sobre ele.
Alyssa Rock
Gerente de Comunidade, The Good Docs Project
Uma coisa continua clara: os desenvolvedores dão valor a uma boa documentação (principalmente porque sabem o quanto pode ser doloroso e difícil usar uma ferramenta com documentação ruim). Eles apenas às vezes não sabem o que fazer para que sua documentação seja boa.
Chris Chinchilla
Escritor e Podcaster, chrischinchilla.com
Na nossa comunidade de redatores, temos discussões intermináveis sobre a linguagem, ferramentas e práticas. Porém, estes números mostram que precisamos de ferramental, treinamento e aconselhamento da comunidade que tornem mais fácil para todos escrever documentação de qualidade.
A maioria dos que responderam trabalha com documentação interna e do código. Desde o ano passado, a proporção dos que trabalham em documentação voltada para o cliente diminuiu quatro pontos percentuais.
Ferramentas de autoria de documentação
Editores de texto personalizáveis ainda são a ferramenta de escolha dos autores de documentação. Esses editores são um meio leve, flexível e eficiente de editar textos e código, tornando-os especialmente adequados para escrever documentação.
Porém, neste ano houve uma diminuição de sete pontos percentuais no uso de editores de texto personalizáveis, combinada com um aumento quase equivalente de seis pontos percentuais no uso de páginas do GitHub. Enquanto isso, o Confluence, um dos principais exemplos de documentação colaborativa em wiki, manteve sua posição.
Dos 3% que responderam que usam uma solução profissional de autoria de documentação de ajuda, 42% preferem ferramentas desenvolvidas de forma personalizada. Dentre as demais opções, a única ferramenta mais recente que se destaca é o Paligo, com uma parcela de 5%. As outras opções populares são todas ferramentas tradicionais e bem estabelecidas.
Embora mais de metade daqueles envolvidos em redação técnica não tenha pensado em usar uma ferramenta profissional, uma parcela significativa de 45% está aberta à ideia.
Marcação
O Markdown continua sendo a escolha predominante. Porém, em comparação com o ano passado, há uma clara migração do Markdown-padrão (menos 7 pontos percentuais) e das suas variações (menos 4 pontos percentuais) para aplicações WYSIWYG e semelhantes ao Office (mais 6 pontos percentuais). Será que isso significa que o controle sobre o código-fonte está cedendo lugar à conveniência ou à facilidade de uso?
Verificações automatizadas e qualidade da documentação
Apenas 13% dos participantes usam verificações automáticas na documentação técnica. A ampla maioria escreve seus testes localmente, em vez de usar linters públicos, talvez porque os testes tenham como alvo marcações, links e referências incorretos. Para verificações de linguagem e estilo, prefere-se usar verificadores incorporados.
documentação de APIs
Mais de metade dos que responderam escreve referências de API. Os desenvolvedores estão na frente: 81% dizem que escrevem referências de API. Em seguida, vêm funções como arquiteto (19%), redator técnico (18%) e engenheiro de DevOps (17%). Outras funções estão menos envolvidas nesta tarefa e cargos mais altos como CIO, CEO e CTO têm uma porcentagem pequena (7%) envolvida nesta atividade.
61%
A maioria (61%) gera automaticamente referências à API, diretamente a partir do código, uma prática que indica processos eficientes de documentação. Quanto às ferramentas, o Swagger domina o cenário, com uma parcela de 84%.
2/3
Quase dois terços dos que automatizam a geração de conteúdo ainda sentem a necessidade de melhorar manualmente esse conteúdo. Embora a automação acelere o básico, a entrada manual é essencial para dar contexto e um toque pessoal às referências de APIs.
Idiomas e traduções
O inglês ainda é a linguagem primária mais popular para elaborar documentação técnica. O chinês vem em um distante segundo lugar, perdendo quatro pontos percentuais este ano. O japonês ocupa a terceira posição, tendo ganho sete pontos percentuais desde o ano passado.
Apenas 14% dos que responderam traduzem sua documentação para outros idiomas, com 8% pensando em fazer isso. Estas cifras não mudaram significativamente desde o ano passado.
Obrigado pelo seu tempo!
Esperamos que você tenha achado nosso relatório útil. Compartilhe este relatório com seus amigos e colegas.
Participe do Laboratório de Insights de Tecnologia da JetBrains
Participe de pesquisas e estudos de experiência do usuário para tornar os produtos da JetBrains mais fáceis de usar, porém ainda mais poderosos. Você também terá a oportunidade de ganhar recompensas por participar das nossas pesquisas.
Dados brutos Em breve
Estamos preparando os dados brutos. Você pode deixar o seu e-mail para ser notificado quando os dados estiverem prontos para serem baixados.
Se tiver dúvidas ou sugestões, entre em contato conosco em surveys@jetbrains.com.