Redação Técnica

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.

Que tipo de documentação você escreve?

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.

Quais ferramentas você usa para criar a documentação?

Qual solução profissional de autoria de ajuda você usa?

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.

Você está satisfeito com a sua solução atual?

Notáveis 30% dos que usam ferramentas de autoria de documentação de ajuda estão procurando algo melhor.

Você já pensou em usar uma ferramenta profissional para redação técnica?

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?

Diga-nos o que você acha

Qual linguagem de marcação você utiliza para escrever a documentação técnica?

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.

Você reutiliza o conteúdo entre diferentes documentos/guias?

Você usa modelos para acelerar o processo de redação?

Para que tipo de coisas você configura templates?

Você cria modelos parametrizados (por exemplo, modelos contendo variáveis)?

69% dos que responderam não usam modelos para acelerar a redação, mas a maioria daqueles que os usam os aplicam em diferentes tipos de documentos. Quanto aos modelos dinâmicos com variáveis, as opiniões se dividiram quase igualmente.

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.

Você tem verificações automáticas para documentação técnica?

Que tipos de verificações você tem?

Você automatiza as verificações de linguagem e estilo?

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.

Você escreve referências de API?

Redação de referências de APIs dependendo do cargo

Você gera automaticamente as referências à API a partir do código?

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%.

Quais ferramentas você usa?

Você precisa completar as referências à API geradas automaticamente com conteúdo escrito manualmente?

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.

Qual é o idioma principal no qual você escreve a documentação?

Você traduz a documentação para outros idiomas?

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.