Manifeste pour l'écriture de documents et rapports
Cette page donne un ensemble de recommandations quant aux attentes des encadrants de l'école par rapport à la rédaction de documents écrits pour les différents projets à réaliser au cours de la scolarité. Il ne faut pas considérer cette page comme une liste de recettes à appliquer, mais comme un ensemble de règles à prendre en compte pendant l'écriture de rapports. Les liens suivants donnent déjà des conseils spécifiques à un ensemble d'enseignements :
Chaque règle est présentée de la manière suivante : un éventuel contre-exemple pour illustrer, suivi de quelques lignes expliquant l'objectif à appliquer dans la règle. Il va de soi que la règle la plus importante, c'est la règle zéro :
Remarques de forme
A1 Orthographe et grammaire
A l'époque des vérificateurs d'orthographe et de grammaire, il est particulièrement mal vu de se présenter avec un document qui présente des fautes grossières et/ou nombreuses. User et abuser des logiciels d'aide à la correction (comme Grammalecte ou Aspell) et des outils correction automatique (comme dans votre éditeur favori, par exemple avec flycheck sous Emacs).
A2 Style d'écriture
Le style d'écriture (la façon de s'exprimer) doit être mesuré, et uniforme sur tout le document. C'est particulièrement difficile à obtenir lorsque le document est rédigé à plusieurs. Eviter le style familier, les anglicismes, et les styles ampoulés.
Je peux pas push de commit sur mon repo parce que le serveur est down.
A3 Style de présentation
La forme de présentation doit elle aussi être mesurée et claire. Faire attention aux excès (trop d'images, trop de tableaux …) comme aux manques flagrants (uniquement du texte, par exemple). Utiliser à bon escient les styles (formatage, couleur …) pour augmenter la clarté du document, encore une fois sans faire d'excès. Exposer ses idées de manière nette en début de partie ou de paragraphe.
Remarques de fond
B1 Exposer une démarche claire
Le document doit présenter une démarche méthodique pour résoudre les problèmes. Cette méthode part usuellement du contexte dans lequel le problème est exposé, pour ensuite évoquer un ensemble de phases naturelles. Pour du développement, il peut s'agir de phases d'analyse (conception), de résolution (programmation) et enfin de vérification (test).
B2 Décrire précisément les objets
Quel que soit l'élément présenté dans le document, il doit être décrit d'une manière précise. Même si cela semble formel, une définition est le moyen le plus sûr de prendre le temps de nomme ce dont on parle. C'est aussi l'occasion de se poser la question de l'importance de ces objets.
B3 Structurer son document
3 Déroulement du projet // Exemple de décomposition exagérément profonde 3.1 Base Project : Achievement 0 3.1.1 Création des structures et variables globales 3.1.1.1 Structures globales 3.1.1.1.1 La règle du jeu
Le document doit possèder une cohérence globale. Il est censé présenter des aspects de votre travail qui sont liés entre eux. Utiliser des phrases de transitions. Relier les parties entre elles en les citant ou en utilisant des liens. Éviter de faire des décompositions trop fines. Faire très attention en utilisant les systèmes comme
LaTeX
qui donnent une fausse impression de structure.
Exemples et contre-exemples
C1 Ne pas se cacher derrière des périphrases molles
J’ai ensuite pu commencer ma première tâche : l’amélioration d’une page en prenant example sur une page existante. Depuis la fin de cette première tâche, je travaille sur le développement d’une nouvelle fonctionnalité avec cette fois moins de code existant sur lequel m’appuyer et des mécanismes plus complexes à gérer. J’ai aussi eu besoin d’effectuer plusieurs factorisations de code.
Se mettre à la place du lecteur, pour vérifier que le contexte permet de comprendre chaque notion. Faire l'effort de définir les notions importantes et d'illustrer par des exemples les points obscurs. Faire attention à l'utilisation abusive de pronoms ne se référant à rien de précis.
C2 Ne pas faire de listes stériles
L’ensemble du front-end utilise AngularJS. Côté back-end, l’API originellement codée en OCaml est progressivement migrée vers Node.js. La base de données est gérée à la fois par MongoDB et Elastic-Search. L’administration système est gérée avec les pipelines Bitbucket, Docker et Datacat.
Éviter de noyer le lecteur au fond d'énumérations sans substance. Si chaque élément de la liste est important, il mérite d'être détaillé et placé au centre d'une structure qui lui donne du sens. Sinon, sélectionner et ne conserver que les éléments importants dans la liste.
C3 Ne pas se cacher derrière du code
Nous avons donc créé une fonction initialisation() qui remplit les mains des joueurs.
void initialisation(struct player_card *p) { int a = 0; for (int i = 0 ; i < MAX_JOUEUR; i ++) { for (int j = 0 ; j < 5 ; j ++) { a = ( rand ( ) % 132 ) +1; if ( a>0 && a <21) p−>t[i][0]++; if ( a>20 && a <31) p−>t[i][1]++; if ( a>30 && a <81) p−>t[i][2]++; if ( a>80 && a <131) p−>t[i][3]++; // ...
Cette fonction prend en argument les mains des joueurs et les remplit un par un.
Le code est un langage pour les compilateurs. Les rapports s'adressent à des êtres humains. Il ne faut pas hésiter à illustrer un rapport avec du code, mais ce code ne doit pas être long, et il doit être expliqué de manière intelligible.
C4 Ne pas laisser une figure ou un tableau sans commentaire
Pour montrer la complexité de certains chemins de navigation dans l’application, voici la succession d’écrans jusqu’à arriver au résultat du calculateur pour une solution fille, de gauche à droite : (suivent 7 images non commentées sur une page entière)
Si votre rapport contient des illustrations, c'est que vous estimez qu'elles sont nécessaires pour mieux comprendre un partie de votre travail. Il est indispensable d'expliquer ce qu'elles sont censées illustrer. La remarque tient aussi pour toute forme de courbe, de diagramme et autre dessin.
C5 Citer ses sources
Toute référence à un document externe doit être citée de manière appropriée (en particulier son auteur) et présentée dans une bibliographie. Toute citation d'un texte externe doit être présentée explicitement comme telle, (encadrée par des guillemets ou autres) et ici aussi citée de manière appropriée. Il n'y a pas beaucoup de chemin entre une citation trop longue et un plagiat.