Toss publie son guide de technical writing

Principes clés pour rédiger une bonne documentation technique

1. Définir le type de document

La manière d’écrire efficacement varie selon l’objectif du document.

• Documentation orientée apprentissage : permettre de comprendre l’ensemble lorsqu’on découvre une nouvelle technologie ou un nouvel outil
• Documentation de résolution de problèmes : résoudre un problème précis lorsqu’on possède déjà les connaissances de base
• Documentation de référence : vérifier l’usage d’une fonctionnalité ou d’une API lorsqu’on sait déjà comment utiliser l’outil
• Documentation explicative : comprendre en détail les concepts, les principes et les connaissances de fond

2. Construire la structure de l’information

Comprendre de nouvelles connaissances demande des efforts, mais structurer l’information permet de les réduire.

• Ne traiter qu’un seul sujet par page
• Apporter d’abord de la valeur
• Rédiger des titres efficaces
• Ne pas oublier l’aperçu d’ensemble
• Rendre la structure prévisible

3. Soigner les phrases

Améliorer la clarté des phrases aide le lecteur à comprendre plus facilement le contenu. Si des détails sont formulés dans des phrases difficiles à comprendre, l’efficacité de transmission chute fortement.

• Clarifier le sujet de la phrase
• Ne garder que les informations nécessaires
• Écrire de manière concrète
• Utiliser des formulations naturelles
• Écrire de manière cohérente

[tested]

N’y a-t-il pas un endroit qui rassemble ce genre de sites créés par Toss ?

[dontdieych]

Le style en "-yo" est assez difficile à adopter.

[gera1d]

C’est vrai.

[winterjung]

C’est bien. En particulier, pour la partie sur la reformulation des phrases, je pense qu’il faudrait essayer d’en faire un GPTs en few-shot pour l’utiliser.

[mathgig]

Je trouve que ce genre de texte est une bonne chose. À l’ère des LLM, comment ce type de directives pourrait-il évoluer ?

[bluejoyq]

C’est vraiment un excellent projet ^^