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.
Documentação interna
Documentação do código
Documentação voltada para o cliente
Outros
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.
46%
39%
Um editor de texto personalizável
49%
32%
Confluence ou outra plataforma de wiki
28%
30%
Uma aplicação para escritório
24%
23%
Google Docs
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?
77%
70%
Markdown
18%
24%
Não tenho certeza/utilizo um editor WYSIWYG ou um aplicativo semelhante ao Office
13%
9%
Um tipo personalizado de Markdown
5%
6%
XML/DITA/DocBook/etc.
5%
5%
AsciiDoc
4%
4%
reStructuredText
4%
3%
Outros
Modelos e reutilização de conteúdo
Quase metade dos que responderam usa uma abordagem estruturada à reutilização de conteúdo. Apesar disso, 32% ainda copiam e colam, possivelmente por causa das limitações das suas ferramentas, o que pode causar inconsistências e retardar o processo de documentação.
Sim, armazeno conteúdo reutilizável em trechos de código e faço referência a eles a partir de diferentes documentos
Não, minhas ferramentas não oferecem suporte para reutilização de conteúdo, então copio e colo conteúdo semelhante
Não, não preciso reutilizar conteúdo
Diferentes tipos de tópicos/documentos
Conteúdo repetido, como blocos de advertência
Elementos de marcação complexos
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.
Sim, meu editor tem um corretor ortográfico/gramatical integrado
Não, contamos com revisões
Eu uso um serviço externo
Temos verificações linguísticas automatizadas
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.
81%
68%
Desenvolvedor / Programador / Engenheiro de software
19%
11%
Arquiteto
18%
14%
Escritor técnico
17%
13%
Engenheiro DevOps / Desenvolvedor de infraestrutura / etc.
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%.
Swagger
ReDoc
Outros
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.
Se tiver dúvidas ou sugestões, entre em contato conosco em surveys@jetbrains.com.