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

Quel type de documentation rédigez-vous ?

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.

Quels outils utilisez-vous pour créer de la documentation ?

Quelle solution professionnelle utilisez-vous pour la création d'aide ?

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

Votre solution actuelle vous convient-elle ?

Une part non négligeable (30 %) des personnes utilisant un outil pour la création de ressources d'aide aux utilisateurs disent ne pas en être totalement satisfaites et rechercher une meilleure option.

Avez-vous déjà envisagé d'utiliser un outil professionnel pour la rédaction technique ?

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é ?

Donnez-nous votre avis

Quel langage de balisage utilisez-vous pour rédiger la documentation technique ?

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.

Réutilisez-vous du contenu entre différents documents / guides ?

Utilisez-vous des modèles pour accélérer le processus de rédaction ?

Pour quel genre de choses configurez-vous des modèles ?

Créez-vous des modèles paramétrés (par exemple, des modèles contenant des variables) ?

69 % des répondants n'utilisent pas de modèles pour accélérer la rédaction, mais parmi ceux qui le font, la plupart les appliquent à différents types de documents. Quant aux live templates avec variables, les avis sont partagés, environ la moitié des répondants disent en utiliser.

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.

Disposez-vous de contrôles automatisés pour la documentation technique ?

De quels types de vérifications disposez-vous ?

Automatisez-vous les contrôles pour les langues / le style ?

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

Écrivez-vous de la documentation d'API ?

Rédaction des références d'API selon la fonction professionnelle

Générez-vous automatiquement la documentation d'API à partir du code ?

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

Quels outils utilisez-vous ?

Avez-vous besoin d'ajouter du contenu écrit manuellement à la documentation d'API générée automatiquement ?

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.

En quelle langue écrivez-vous la documentation principalement ?

Traduisez-vous la documentation dans d'autres langues ?

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.

Rédaction technique:

2023

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.

Si vous avez des questions ou des suggestions, contactez-nous à surveys@jetbrains.com.