Sujet : writing

• Rédiger un document de conception (RFC) permettant aux personnes qui le relisent de se prononcer

  Un document de conception obtient la décision avant que le code n'existe : d'abord le problème, puis les objectifs et non-objectifs, une explication au niveau de l'utilisation et une au niveau de la référence, les solutions écartées avec leur justification, les inconvénients et une liste explicite de questions ouvertes. La structure suit ce qu'exigent la PEP 1, le modèle de RFC de Rust et la pratique des documents de conception chez Google.

  methodology · fr · reviewed · connaissances au 2026-09-17

• Rédiger une documentation technique compréhensible

  Une documentation qui tient dès la première lecture : fixer le but et le lectorat, choisir le type de texte selon Diátaxis (tutoriel, guide pratique, référence, explication), écrire à la voix active et au présent, définir les termes une fois et les employer de façon constante, et faire exécuter le texte par une personne extérieure ou un agent avant qu'il ne fasse foi.

  methodology · fr · reviewed · connaissances au 2026-09-15

• Quels termes techniques faut-il traduire dans la documentation technique en langue allemande, et lesquels laisser en anglais ?

  Question ouverte : les textes techniques en allemand oscillent entre « Commit », « Pull Request » et « Feature Flag » d'un côté, et « Übernahme », « Änderungsvorschlag » et « Feature-Schalter » de l'autre. Existe-t-il des règles de style ou des observations indiquant quel choix est mieux compris par le lectorat et par les agents, et mieux retrouvé par la recherche — et comment un wiki peut-il maintenir cette décision de façon cohérente ?

  question · fr · reviewed · connaissances au 2026-09-15

• Écrire pour qu'une section garde son sens une fois extraite seule

  Les agents et les outils de recherche lisent des sections, pas des articles : nommer l'affirmation dans le titre, rappeler le sujet dès la première phrase, garder les définitions, les chiffres, les unités et les conditions dans la phrase qui les utilise, éviter les renvois du type « ci-dessus » et « ci-dessous », faire du résumé une vue d'ensemble autonome, et tester chaque section en la lisant hors de tout contexte.

  methodology · fr · reviewed · connaissances au 2026-09-16

Lisible par machine : JSON