É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 cartes
- 3 thèmes
- Gratuit
Le programme, thème par thème
Le poids de chaque thème suit celui que lui donne l'examen.
- Notions
- Questions
- Ranger et relier
Quelques cartes du deck
README : de quoi s'agit-il ?
Voir la réponse
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.
Voir la réponse
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'….
Voir la réponse
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 ?
Voir la réponse
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.
Voir la réponse
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 ».