Écrire une documentation technique en anglais
Le plan d'un README, les règles du style technique, la docstring et les fautes que font les francophones : articles, noms indénombrables, allow to, prépositions, ordre des mots.
- 28 cards
- 3 topics
- Free
The outline, topic by topic
Each topic is weighted the way the exam weighs it.
- Notions
- Questions
- Ranger et relier
A few cards from the deck
README : de quoi s'agit-il ?
Show the answer
Fichier placé à la racine d'un projet, qui le présente : à quoi il sert, comment l'installer et l'utiliser.
C'est la première page qu'un visiteur lit, souvent affichée d'office par la forge (GitHub, GitLab) : elle doit dire en quelques lignes à quoi sert le projet avant d'entrer dans le détail.
Tu décris ce que permet une bibliothèque. Quelle phrase est correcte ?
- This library allows you to send data to the server.
- This library allows to send data to the server.
- This library permits to send data to the server.
- This library allows you sending data to the server.
Show the answer
This library allows you to send data to the server.
« Allow » et « permit » veulent un complément : « allow you to… ». « Allow to » calque le français « permet d'envoyer ». On peut aussi écrire « lets you send ».
Une étape de procédure commence par un verbe à l'… et ne contient qu'….
Show the answer
Une étape de procédure commence par un verbe à l'impératif et ne contient qu'une seule action.
« Open the file. Click Save. » vaut mieux que « Open the file and click Save », où l'on ne peut pas dire à quelle action une erreur se rapporte.
Docstring : de quoi s'agit-il ?
Show the answer
Texte de documentation placé juste sous la signature d'une fonction, d'une classe ou d'un module Python.
Python la garde en mémoire : help(fonction) l'affiche, et les outils de documentation la lisent. Une fonction bien nommée se complète par une docstring courte et exacte.
Tu décris une dépendance entre deux fichiers. Quelle phrase est correcte ?
- The module depends of the config file.
- The module depends on the config file.
- The module depends from the config file.
- The module depends to the config file.
Show the answer
The module depends on the config file.
« Depend » se construit avec « on ». Les autres prépositions calquent le français « dépend de ». Même piège avec « consist of », « connect to » et « responsible for ».