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.

Que tipo de documentação você escreve?

87%

Documentação interna

63%

Documentação do código

53%

Documentação voltada para o cliente

1%

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.

Quais ferramentas você usa para criar a documentaçã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

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

42%

Solução personalizada

29%

Adobe FrameMaker

22%

Ajuda e Manual

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

Outros

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?

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.

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

47%

Sim, armazeno conteúdo reutilizável em trechos de código e faço referência a eles a partir de diferentes documentos

32%

Não, minhas ferramentas não oferecem suporte para reutilização de conteúdo, então copio e colo conteúdo semelhante

21%

Não, não preciso reutilizar conteúdo

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

Para que tipo de coisas você configura templates?

78%

Diferentes tipos de tópicos/documentos

48%

Conteúdo repetido, como blocos de advertência

29%

Elementos de marcação complexos

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?

61%

Marcação quebrada

56%

Links externos quebrados

53%

Recursos faltando

52%

Referências internas quebradas

47%

Estrutura de documento com erro

38%

Amostras de código com erro

6%

Outros

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

54%

Sim, meu editor tem um corretor ortográfico/gramatical integrado

22%

Não, contamos com revisões

13%

Eu uso um serviço externo

12%

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.

Você escreve referências de API?

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

81%

68%

Desenvolvedor / Programador / Engenheiro de software

19%

11%

Arquiteto

18%

14%

Escritor técnico

17%

13%

Engenheiro DevOps / Desenvolvedor de infraestrutura / etc.

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?

84%

Swagger

9%

ReDoc

15%

Outros

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?

62%

Inglês

18%

Chinês

13%

Japonês

2%

Francês

1%

Espanhol

1%

Coreano

1%

Alemão

2%

Outros

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.

Redação Técnica:

2023

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.