Rédaction technique
Partager :
Ces questions n'ont été posées qu'aux personnes ayant indiqué être impliquées dans la rédaction technique.
12 % des répondants ont déclaré prendre part à la rédaction technique, alors que seulement 10 % d'entre eux occupent offciellement un poste de rédacteur technique.
En 2023, 90 % des personnes qui rédigent de la documentation ne sont donc pas rédacteurs techniques. Cela amène à s'interroger sur la collaboration entre les équipes, sur la qualité et la cohérence de la documentation et sur le rôle de rédacteur technique.
Daniele Procida
Directeur de l'ingénierie, Canonical
La documentation ne se limite pas à la rédaction de contenus techniques. Elle façonne la relation d'un utilisateur avec un produit. Elle influence aussi la façon dont les créateurs d'un produit le perçoivent et toutes les personnes impliquées dans la création d'un produit devraient participer à la reflexion sur sa documentation.
Alyssa Rock
Community Manager, The Good Docs Project
Il est clair que les développeurs sont conscients de l'importance de disposer d'une documentation de qualité, principalement parce qu'ils savent à quel point il peut être pénible et difficile d'utiliser un outil dont la documentation est médiocre, mais il ne savent pas toujours comment améliorer leur documentation.
Chris Chinchilla
Rédacteur et podcasteur, chrischinchilla.com
Au sein de la communauté des rédacteurs, nous avons des discussions sans fin sur des questions de linguistique, les meilleurs outils et les bonnes pratiques. Ces chiffres montrent que les rédacteurs ont besoin de davantage d'outils, de formations et de partage de conseils entre les membres de la communauté, pour permettre à tous de produire de la documentation de qualité.
La plupart des répondants disent rédiger de la documentation interne et a documentation de code. La proportion de personnes travaillant sur la documentation destinée aux clients a baissé de quatre points de pourcentage depuis l'année dernière.
Outils de création de documentation
Les éditeurs de texte personnalisables restent le type d'outils privilégié des auteurs de documentation car ils consituent un moyen léger, flexible et efficace de modifier du texte et du code.
Toutefois, on observe cette année une baisse de l'utilisation d'éditeurs de texte personnalisables de sept points de pourcentage dans, couplée à une augmentation presque équivalente (six points de pourcentage) de l'utilisation de pages GitHub. Confluence, la référence en matière de documentation wiki collaborative, maintient sa position.
Sur les 3 % de personnes qui ont recours à une solution professionnelle pour la création de ressources d'aide aux utilisateurs, 42 % préfèrent utiliser un outil sur mesure. Les autres types d'option populaires sont des outils déjà bien établis. Le seul outil récent qui se démarque est Paligo, avec un score de 5 %.
Bien que plus de la moitié des personnes impliquées dans la rédaction technique n'aient pas pensé à essayer un outil professionnel, 45 % d'entre elles envisagent de le faire.
Balisage
Markdown reste prédiominant. Cependant, par rapport à l'année dernière, on constate un recul du Markdown standard (en baisse de 7 points de pourcentage) et de ses variantes (en baisse de 4 points de pourcentage) au profit des applications WYSIWYG et de type Office (en hausse de 6 points de pourcentage). Cela signifie-t-il que le contrôle des sources serait en train de passer au second plan par rapport à des critères comme la commodité ou la convivialité ?
Réutilisation de contenus et modèles
Près de la moitié des répondants utilisent une approche structurée pour réutiliser du contenu. Mais 32 % d'entre eux continuent de faire du copier-coller, peut-être en raison des limites des outils dont ils disposent, ce qui peut entraîner des incohérences et ralentir le processus de documentation.
Contrôles automatisés et qualité de la documentation
Seules 13 % des répondants ont recours à des vérifications automatisées pour la documentation technique. La grande majorité d'entre eux écrivent leurs tests en interne plutôt que d'utiliser des linters publics, probablement parce que les tests ciblent les balises, les liens et les références cassés. Pour les vérifications relatives aux langue et au style, leur préférence va aux correcteurs d'orthographe intégrés.
Documentation d'API
Plus de la moitié des répondants écrivent de la documentation d'API. Les développeurs arrivent en tête (81 % déclarent rédiger de la documentation d'API), suivis par les architectes (19 %), les rédacteurs techniques (18 %) et les ingénieurs DevOps (17 %). Les personnes occupant des postes de direction (générale, informatique ou technologique) sont peu impliquées (7 %) dans cette activité.
61 %
La majorité des répondants (61 %) génère automatiquement la documentation d'API directement à partir du code, ce qui est révélateur de l'efficacité de ses processus de documentation. En ce qui concerne les outils utilisés, Swagger prédomine avec 84 %.
2/3
Environ deux tiers des personnes ayant recours à l'automatisation déclarent toujours ressentir le besoin d'améliorer manuellement le contenu généré automatiquement. L'automatisation permet d'accélerer les tâches de base, mais la contribution humaine reste essentielle pour ajouter des éléments de contexte et apporter une touche personnelle à la documentation des API.
Langues et localisation
L'anglais est de loin la langue la plus utilisée pour la documentation technique. Le chinois arrive en deuxième place, mais loin derrière, et perd quatre points de pourcentage cette année. Le japonais se classe en troisième position et a gagné sept points de pourcentage depuis l'année dernière.
Seuls 14 % des répondants disent traduire leur documentation dans d'autres langues et 8 % d'entre eux envisagent de la faire. Ces chiffres n'ont pas beaucoup évolué depuis l'année dernière.
Merci du temps que vous nous avez accordé !
Nous espérons que vous avez trouvé ce rapport intéressant. N'hésitez pas à le partager avec vos amis et collègues.
Rejoignez le JetBrains Tech Insights Lab
Participez à des enquêtes et à des études sur l'expérience utilisateur pour aider les produits JetBrains à gagner en facilité d'utilisation, mais aussi en puissance. En participant à nos études, vous aurez également la possibilité de gagner des récompenses.
Données brutes Bientôt disponibles
Nous sommes en train de préparer les données brutes. Vous pouvez laisser votre adresse e-mail pour recevoir une notification lorsqu'elles seront disponibles au téléchargement.
Si vous avez des questions ou des suggestions, contactez-nous à surveys@jetbrains.com.