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 ?

87%

Documentation interne

63%

Documentation du code

53%

Documentation destinée aux clients

1%

Autre

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 ?

46%

39%

Un éditeur de texte personnalisable

49%

32%

Confluence ou autre plateforme wiki

28%

30%

Une application Office

24%

23%

Google Docs

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

42%

Solution personnalisée

29%

Adobe FrameMaker

22%

Help & Manual

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

Autre

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 ?

77%

70%

Markdown

18%

24%

Je ne sais pas / J'utilise un éditeur WYSIWYG ou une application de type Office

13%

9%

Une version personnalisée de Markdown

5%

6%

XML / DITA / DocBook / etc.

5%

5%

AsciiDoc

4%

4%

reStructuredText

4%

3%

Autre

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 ?

47%

Oui, je stocke du contenu réutilisable dans des snippets et je les référence à partir de différents documents

32%

Non, mes outils ne permettent pas de réutiliser du contenu, alors je copie-colle le contenu similaire

21%

Non, je n'ai pas besoin de réutiliser du contenu

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

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

78%

Différents types de sujets/documents

48%

Contenu répétitif comme les blocs d'admonition

29%

Éléments de balisage complexes

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 ?

61%

Balises cassées/corrompues

56%

Liens externes cassés

53%

Ressources manquantes

52%

Références internes cassées

47%

Structure du document endommagée

38%

Exemples de code cassés

6%

Autre

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

54%

Oui, mon éditeur a un correcteur orthographique / grammatical intégré

22%

Non, nous faisons confiance aux révisions

13%

J'utilise un service externe

12%

Nous avons des vérifications linguistiques automatisées

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

81%

68%

Développeur / Programmeur / Ingénieur logiciel

19%

11%

Architecte

18%

14%

Rédacteur technique

17%

13%

Ingénieur DevOps / Développeur d'infrastructures

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 ?

84%

Swagger

9%

ReDoc

15%

Autre

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 ?

62%

Anglais

18%

Chinois

13%

Japonais

2%

Français

1%

Espagnol

1%

Coréen

1%

Allemand

2%

Autre

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.