Voir la source de Rédaction de documents écrits

L'objet de cette page est de définir les règles d'écriture de documents écrits (comptes-rendus de TP, projets de spécialité, rapports de PFE, notes de synthèse SHEME, ''etc.'') à l'Ensimag. Ces règles sont valables pour les 3 années du cursus, et devraient être assimilées le plus tôt possible.

Cette page comporte des recommandations générales applicables à tout document écrit. Il comporte également des règles spécifiques à différents types de documents (documents techniques, comptes-rendus de stages, ...) et à différentes disciplines (informatique, mathématiques appliquées, ...)

Certains types de travaux requièrent la rédaction de documents plutôt courts (moins de cinq pages). De tels documents ne se prêtent pas à l'inclusion d'une table des matières, bibliographie, introduction présentant le contexte général et la motivation du sujet, ''etc.'' Leur rédaction est cependant soumise au respect des autres règles générales ci-après.
{| class="wikitable"
|-
| Conseils pour l'affichage de cette page : la numérotation des sections qui apparaît dans la table des matières n'est pas reflétée dans le corps de cette page. Pour faire apparaître cette numérotation, cliquez sur [{{fullurl:Sp%C3%A9cial:Pr%C3%A9f%C3%A9rences}} Spécial:Préférences] puis dans l'onglet « Apparence » cliquer sur « Numéroter automatiquement les titres de section ». Les enseignants pourront faire référence à cette numérotation de sections lors de la correction de vos documents écrits.
|}


__TOC__

== Le minimum vital, pour tous les documents écrits {{Ancre|minimum-vital}} ==

=== Enjeux et Objectifs pédagogiques du document {{Ancre|enjeux}} ===

Avant de se lancer dans la rédaction d'un document écrit, il faut d'abord
avoir compris ''à quoi'' sert ce document et ''à qui'' il s'adresse. En
général, les documents demandés dans le cadre de la scolarité ont les
objectifs suivants.

* Entraîner les étudiants à rédiger de tels documents : au cours de leur future carrière, ils auront souvent à rédiger des documents devant faciliter la réutilisation ou l’évaluation de leurs réalisations. Savoir bien rédiger est une compétence essentielle des ingénieurs. 

* Aider les étudiants à acquérir des méthodes de travail liées à la rédaction de documents. En effet, la rédaction est une étape du travail qui favorise la prise de recul par rapport aux tâches effectuées. Par conséquent, il est conseillé d'effectuer la rédaction au fur et à mesure du travail, afin de bénéficier de ce recul pour ''guider'' la réalisation des tâches futures requises par ce travail, et pour avoir un regard critique sur les tâches effectuées. Si l'on prend l'exemple d'un TP, il est dommage de s'apercevoir seulement à la fin, en cours de rédaction, qu'on aurait pu faire beaucoup mieux en s'y prenant autrement. De plus, le recul que manifeste le document écrit vis-à-vis du travail effectué est un critère déterminant dans l'évaluation de ce document.

* Permettre aux enseignants d'évaluer '''rapidement''' le travail des étudiants : le document doit donner des informations synthétiques et pertinentes qui '''aident''' le correcteur à appréhender facilement le travail effectué (en rédigeant, essayer de se mettre dans la peau de l'enseignant qui va corriger). 

{| class="wikitable"
|-
| Conseil : si les objectifs du rapport à écrire ne sont pas clairs, il faut demander des précisions aux enseignants responsables.
|}

<div id="titre"><!-- ancien nom --></div>
=== Titre, en-tête, ... {{Ancre|qqoqc}} ===

Un document papier (ou destiné à être imprimé) doit garder du sens si on le sort de son contexte. Il est donc impératif qu'il mentionne (sur une page de couverture s'il y en a une) au minimum :

* le nom des auteurs,
* l'affiliation des auteurs (i.e. le nom de l'école),
* la date,
* l'objet du document (matière concernée, enseignant, ...).

On peut utiliser le moyen mnémotechnique du [http://fr.wikipedia.org/wiki/QQOQCCP QQOQC ou l'une de ses variantes].

=== Numérotation des pages, en-tête, pied de page {{Ancre|pages}} ===

Numéroter les pages permet à un lecteur de noter des remarques page par page, et à quelqu'un qui cite votre document de le citer précisément (e.g. « comme le dit XXX dans le document YYY pages 42-45, ... »).

Pour un document long, il est intéressant d'inclure le numéro de page dans un en-tête ou pied de page qui rappelle les données importantes sur le document (titre, auteur, date, éventuellement section courante ...).

=== Orthographe et grammaire {{Ancre|orthographe}} ===

* Relisez-vous, ou mieux, faites relire les passages que vous avez écrits par un camarade, afin de vérifier l'orthographe, la grammaire et le style de votre document.
* Passez également votre document au correcteur orthographique (<code>aspell</code> sous linux, menu « tools/spell checking » sous <code>emacs</code>), et grammatical si possible (inclus dans Microsoft Word).
* Respectez les conventions typographiques en français (attention : en anglais elles sont différentes) [http://fr.wikipedia.org/wiki/Wikip%C3%A9dia:Conventions_typographiques http://fr.wikipedia.org/wiki/Wikipédia:Conventions_typographiques].<br>Pour ne citer que les principales : les espaces avant les points virgules, deux points, ''etc.'' ; les locutions latines en italiques sauf si elles ont été incorporées à la langue française, les guillemets, les règles de césure, les unités, les quantités numériques.

=== Nombre de pages du document ===

Lorsqu'on donne une taille limite pour le document dans l'énoncé (par exemple 10 pages), c'est une contrainte forte : il ne faut pas la dépasser.
Réciproquement, un document faisant moins des deux tiers de cette limite doit éveiller la méfiance : est-ce qu'on n'a pas oublié des parties importantes ?

{| class="wikitable"
|-
| Conseil : si le nombre de pages attendu pour le document n'est pas spécifié, mieux vaut demander des précisions aux enseignants responsables.
|}

== Recommandations générales pour les rapports de travaux techniques ==
Note : le terme de « travaux techniques » (TT en abrégé) fait référence aux travaux pratiques, projets de spécialité, projets de fin d'études, et de manière générale à des travaux à dominante technique (informatique ou mathématique à l'Ensimag). Ce terme peut être défini par opposition aux Sciences humaines, économiques, du management et de l'entreprise (Sheme), qui donnent lieu à la rédaction de documents écrits obéissants à d'autres règles de rédaction que celles ci-dessous.

=== Objectifs d'un TT ===

* En général, un TT vise à vous faire manipuler de nouveaux concepts afin d'acquérir des connaissances expérimentales (pratiques) liées à ces concepts. L'acquisition de ces connaissances peut se faire en confrontant des savoirs théoriques relatifs à un sujet donné, à une situation pratique. Il est donc essentiel d'interpréter les résultats obtenus au cours du TT, vis-à-vis du cours ou de questions théoriques incluses dans le TT.

<div id="Demarche">
* Un TT s'articule autour d'un ou plusieurs problèmes. Il vise à mettre en œuvre une démarche générale de résolution de problème fondée sur l'analyse du problème, la modélisation, la mise en œuvre et l'expérimentation, l'analyse critique et l'interprétation des résultats, la formulation de pistes potentielles pour approfondir la méthode de résolution proposée.</div>

<div id="Plan">
=== Plan du rapport ===

Un sujet de TT peut contenir plusieurs questions numérotées, qui sont en général une aide à la mise en place de la [[#Demarche|démarche de résolution]]. Pour autant, un rapport dont le plan reproduit exactement l'intitulé et l'ordre des questions n'est pas forcément un plan pertinent. Un tel plan ne sera adopté que si l'énoncé le demande explicitement.

À défaut, le plan pourra s'articuler autour des rubriques suivantes.</div> 

* Introduction axée sur la présentation du problème (essentiellement à l'aide d'éléments factuels).
* Analyse du problème et proposition d'une méthode de résolution.
* Mise en œuvre de cette méthode de résolution sur des instances du problème (par exemple des cas fictifs ou « jouets », puis des cas réels ou plus généraux).
* Analyse des résultats obtenus, commentaire, interprétation.
* [[#Conclusion|Conclusion]].

<div id="Conclusion">

=== Conclusion ===

<div id="Conclusion_scientifique">
La conclusion doit comporter une synthèse de votre travail, et éventuellement une partie scientifique visant à proposer des pistes d'extension pour la résolution, si ces pistes dépassent visiblement du cadre délimité (souvent implicitement) par le sujet. 
<div id="Bilan_humain">
Elle peut comporter, si c'est demandé dans l'énoncé, quelques mots sur l'organisation du travail dans votre binôme / trinôme, un bilan humain, ''etc.'' Suivant la nature du rapport, l'équilibre entre les parties « scientifique » et  « bilan humain » peut varier.
Pour résumer, une conclusion doit vérifier les « trois P » : 
* Positive (mettre en valeur votre travail) 
* Personnelle (surtout si elle comporte une partie « bilan humain »   
* Prospective (présenter des pistes futures sur le sujet)

=== Expérimentations ===

De nombreux TT comportent une partie consistant à étudier l'effet de facteurs ''A'', ''B'', ''C'', ... sur une quantité ''X''. Ainsi, ''X'' peut-être vue comme une fonction ''X = f(A,B,C,...)''. Pour étudier l'effet des différents facteurs sur ''X'', on est amené à faire varier leur valeur. Il faut expliquer et justifier dans tous les cas le protocole (la stratégie) que vous avez choisie pour les faire varier. En général, on ne fait pas varier tous les facteurs simultanément, sinon leur interprétation devient très délicate. Par exemple, on choisit des valeurs par défaut (un peu neutres si possibles) ''a1'', ''b1'', ''c1'' puis on remplace ''a1'' par ''a2'', ''a3'', ... tout en fixant les valeurs de ''B'' à ''b1'', de ''C'' à ''c1'', ''etc.'' Le choix d'échelle de ''a2'', ''a3'', ... doit être justifié par une analyse préalable : l'échelle linéaire (0, 10, 20, ...) n'est pas toujours la plus pertinente. Il existe aussi des échelles exponentielles (1, 10, 100, ...) ou logarithmiques (ln(10), ln(20), ln(30), ...).

On résume ensuite les résultats à l'aide de tableaux, ou figures (notamment si les facteurs sont quantitatifs). Il faut éviter de mettre la liste des valeurs de ''X'' obtenues dans le corps du rapport (sauf si cette liste est vraiment courte et parlante).

=== Citations ===

Un des enjeux pour votre lecteur est d'évaluer à quel point votre travail est authentique, personnel et original. Afin de clarifier ceci, il est important d'adopter la convention suivante :
* Tout résultat (théorème, équation, calcul, algorithme,...) doit être démontré ou issu d'une citation.
* S'il est démontré sans qu'une citation soit effectuée, le lecteur pensera que vous êtes l'auteur de la preuve. Si ce n'est pas le cas, détrompez-le en citant l'auteur original (qui peut être un enseignant de l'école, l'auteur d'un livre, d'un article, ou au pire un de vos copains si vous êtes très paresseux ou s'il est très brillant :-)
* Pour effectuer une citation, utilisez l'une des conventions suivantes : http://j.poitou.free.fr/pro/html/typ/biblio.html
* Profitez de la lecture de la page web de Jacques Poitou ci-dessus pour vous familiariser avec la notion de plagiat. Le plagiat est sanctionné à l'Ensimag, cf. la [http://intranet.ensimag.fr/teide/Charte_contre_la_fraude.php Charte contre la fraude].
* En pratique pour faire une bibliographie en LaTeX c'est très simple : il suffit de choisir un fichier de style et de créer un fichier BibTeX. Voir la page [[Utiliser BibTeX pour un rapport de recherche]] sur Ensiwiki, ou l'une des références dans la partie [[Utiliser_BibTeX_pour_un_rapport_de_recherche#Plus_d.27information_sur_BibTeX|Plus d'information sur BibTeX]] de cette page.
Ces fichiers sont adaptés à une bibliographie en anglais, on vous pardonnera si les noms des auteurs sont séparés par des ''and'' plutôt que ''et''.
* Microsoft Word permet aussi de gérer la bibliographie. Par exemple dans la version 2007, aller dans le menu ''Références'', puis ''Insérer une citation'', puis ''Ajouter une nouvelle source''. La citation associée à cette source sera alors insérée après le curseur. Pour insérer la bibliographie dans le rapport, aller dans le menu ''Références'', puis ''bibliographie'', puis de nouveau ''bibliographie''.
* En définitive, une citation ressemble à ceci : « Pour calculer la fonction Gamma, nous utilisons l'équation 6.1.5 dans Abramowitz ''et al.'' (1964) ». Le rapport comportera alors, en fin de document, une partie analogue à celle ci-dessous :

=== Références ===

Abramowitz, Milton and Irene A. Stegun (1964), ''Handbook of mathematical functions with formulas, graphs, and mathematical tables''. New York: Dover.

=== Figures et tableaux ===
<div id="Figures"> </div>

* Les figures doivent être numérotées, légendées, référencées dans le texte par leur numéro. Les axes éventuels doivent porter des noms explicites et des graduations. La ''légende'' est une phrase située juste au-dessous ou au-dessus de la figure et comportant au moins un titre expliquant ce que représente la figure. Si différents figurés sont utilisés (pour tracer différentes courbes superposées, ou pour représenter des points de différentes classes, ''etc.''), une deuxième légende est ajoutée à l'intérieur de la figure proprement dite.

* Si vous souhaitez retoucher des graphiques, il peut être utile de les enregistrer au format [http://fr.wikipedia.org/wiki/Scalable_Vector_Graphics SVG]. Vous pourrez alors y ajouter des éléments graphiques supplémentaires, modifier les légendes des axes, ''etc.'' (à l'aide d'[http://inkscape.org inkscape] par exemple). Inkscape permet d'exporter des figures SVG au format EPS (ou JPG,...) pour les inclure dans un document LaTeX (N.B. Microsoft Word permet aussi l'inclusion de figures EPS et JPG, entre autres).

* Réfléchissez à plusieurs façons de représenter graphiquement l'idée que vous vouliez illustrez, et choisissez celle qui vous semble la plus pertinente. Par exemple si vous voulez illustrer le fait que ''f(x)'' tend vers 0 quand ''x'' tend vers plus l'infini, peut-être vaut-il mieux représenter ''|f(x)|'' en fonction de ''x'' [[Media:Exemple_figure.jpg|(Exemple de figure)]].

* Faites bien référence à chaque figure dans votre texte. Si vous ne l'avez pas fait, c'est peut-être que cette figure n'est pas bien utile (supprimez-la alors), ou que vous êtes passé à côté de l'occasion de faire un commentaire pertinent sur le phénomène étudié.

* Des recommandations analogues s'appliquent aux tableaux.

* Si une ligne ou une colonne de votre tableau représente des quantités ordinales, réfléchissez à la possibilité de représenter ce tableau sous forme de figure. Illustration : le tableau suivant
{| class="wikitable"
|-
! n
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
| 10
| ...
|-
! f(n)
| 1
| 4
| 9
| 16
| 25
| 36
| 49
| 64
| 81
| 100
| ...
|} sera avantageusement remplacé par une figure avec la ligne 1 en abscisse et la ligne 2 en ordonnée.

=== Formules mathématiques ===

* Respecter la priorité (c'est-à-dire l'imbrication) entre les différents types de parenthèses : {[()]}. Par exemple, ne pas imbriquer uniquement des parenthèses entre elles.

* La ponctuation s'applique aux formules mathématiques. Elles doivent donc notamment comporter un point si c'est la fin d'une phrase, peuvent être suivies d'une virgule si elles sont incluses dans une phrase (ponctuez la formule comme si vous lisiez l'intégralité de la phrase à voix haute). Exemple : « Nous avons répété la procédure pour chacune des 5!, c'est-à-dire 120, permutations de notre ensemble E d'origine (vu que card(E)=5). »

* En règle générale, pour écrire des mathématiques, il vaut mieux utiliser un éditeur d’équations ou le format mathématique de LaTeX. Les réglages par défaut sont satisfaisants et correspondent aux conventions anglosaxonnes. <br> Dans l’alphabet latin, les minuscules qui correspondent à des variables, des inconnues, des indices, etc., sont écrites en italique. Néanmoins, sont écrits en romain les identificateurs de fonctions et constantes prédéfinies :
: - les noms des fonctions usuelles sin, cos, ln, log, exp, etc.;
: - les constantes e (= exp 1), i (base des imaginaires purs), le symbole d (pour écrire un « élément différentiel » d ''t'' ou d ''x''). <br> Pour les majuscules latines, en revanche, on emploie de préférence le romain lorsqu’il s’agit de points, de variables ou d’indéterminées. Mais pour les ensembles (en particulier les ensembles de points en géométrie, comme les droites, plans, cercles, courbes, etc.), on a intérêt à utiliser des italiques, voire des cursives : la courbe <math>{\mathcal{C}}</math>, la droite <math>{\mathcal{D}}</math>, le plan <math>{\mathcal{P}}</math>. Notons que dans ce cas, il n’est pas indispensable de mettre le symbole entre parenthèses. Il vaut mieux répéter à chaque fois la nature de l’objet : « Soit M un point de la droite <math>{\mathcal{D}}</math>...» <br> Les chiffres et les signes opératoires ou relationnels (« + », « < », ...) sont toujours en romain. <br> Une attention toute particulière sur deux points : 
: - pour désigner une quantité, notamment un indice par la lettre ''l'', il vaut mieux utiliser la cursive <math>\ell</math>;
: - pour le signe de multiplication, il ne faut pas employer la lettre x ou X, mais le signe spécial <math>\times</math>. <br> Les ensembles de nombres sont normalement écrits en gras dans un texte imprimé : <math>{\boldsymbol{\mathrm{Z}}}</math>, <math>{\boldsymbol{\mathrm{C}}}</math>, les caractères « éclaircis » <math>{\mathbb{Z}}</math>, <math>{\mathbb{C}}</math> étant en principe réservés à l’écriture au tableau -- mais il faut bien admettre que cette convention est rarement appliquée. Ne pas manquer de rappeler les conventions en début de texte chaque fois qu’il peut y avoir ambiguïté.<br> Sources : 
: - [[Media:txtscientifique.pdf | http://mathematiques.ac-bordeaux.fr/txtoff/txtref/txtscientifique.pdf]]
: - Lexique des règles typographiques en usage à l'Imprimerie Nationale (2002). Imprimerie Nationale.

=== Erreurs classiques à éviter ===

Quelques erreurs à éviter :

* Que la conclusion attendue soit une [[#Conclusion_scientifique|conclusion scientifique]] ou un [[#Bilan_humain|bilan humain]], on ne peut se contenter de dire « ce travail m'a beaucoup apporté dans ma scolarité ».

* Afficher des quantités avec un nombre inadéquat de chiffres significatifs.

* Afficher des grands nombres sans espace entre les milliers. Il faut écrire : « il y a 20 708 500 façons de choisir 3 éléments parmi 500 » (et non pas 20708500).

=== Style ===

==== Tournures personnelles {{Ancre|personnel}} ====

En général, on évite les tournures personnelles (« je ») dans les documents techniques, sauf (éventuellement) pour insister sur la contribution de l'auteur. Ce n'est pas incorrect de dire « je vais présenter ceci en section 2 » ou « j'ai réalisé cela pendant mon projet », mais on lit plus souvent « nous verrons ceci en section 2 » (nous = moi + le lecteur) ou « cela a été réalisé pendant le projet ». En anglais en particulier, la forme passive est souvent utilisée pour éviter d'avoir à préciser le sujet d'une phrase (e.g. "this has been done" au lieu de "I did this"), mais attention à ne pas en abuser.

== Recommandations particulières à certains travaux techniques ==

=== Recommandations particulières aux TP d'informatique ===

==== Quelques exemples de rubriques à développer éventuellement suivant le TP ====
En cas de doute, demandez à votre enseignant.

* dans la conclusion ou l'introduction: les points réalisés par rapport au sujet, points non réalisés, bogues ou problèmes connus (non corrigés), précisions par rapport aux ambiguïtés ou aux incohérences du sujet.

* description de l'implémentation: choix de conception additionnels par rapport au sujet (procédures auxiliaires, adaptation des structures de données, invariants sur les données, algorithmes utilisés ne figurant pas dans le sujet, etc).

* description de la démarche de validation: objectifs/nature des tests, couverture, programmation pour la mise-en-oeuvre (pilote de tests, scripts de non-régression, oracles, etc), utilisation d'outils annexes (valgrind, calcul de couverture via gcov, etc), synthèse des résultats obtenus.

* mesures de performances: nature de ce qui est mesuré, méthode de la mesure (outils time, gprof, gcov, etc), choix des jeux de tests, évaluation de la fiabilité de la mesure, synthèse des résultats obtenus et interprétation des résultats.

* organisation et gestion de projet: planification et partage des tâches, utilisation d'outils collaboratifs (git, wiki) ou d'aide au développement.

==== À éviter (sauf mention contraire explicite dans le sujet) ====
* inclure du code source dans le rapport (en général, il est à rendre sur Teide ou à inclure en annexe).
* paraphraser du code en français.
* ré-expliquer du code ou un algo fourni par les enseignants.
* liste des bogues corrigés.

=== Recommandations particulières aux rapports à dominante « mathématiques appliquées » ===

* En général le code que vous avez écrit ne nous intéresse pas outre mesure : ne l'incluez pas sauf s'il est très court, ou mettez-le en annexe. Ce qui nous intéresse, c'est l'algorithme, ou de manière plus générale, le principe détaillé de la méthode. Par exemple, les deux solutions suivantes sont acceptables.
** Soit écrire « Nous disposons de 100 mesures (échantillon de taille 100). Mille fois de suite et indépendamment chacune des 1 000 fois : on tire une partition aléatoire de l'échantillon en deux sous-échantillons de taille égale. Parmi ces 1 000 tirages, on compte la fréquence des cas où la moyenne empirique du premier sous-échantillon est supérieure à celle du deuxième. »)
** Soit fournir le <code>R</code> ci-dessous (noter la présence de commentaires qui expliquent ce que fait le code) : 
<code> 
   n = length(x) # taille d'un echantillon x
   m = 1000 # nombre de permutations aleatoires
   sup = rep(0, m) # tableau de booleens : comparaison des moyennes de deux sous-echantillons aleatoires
   for (i in 1:1000) {
      p = sample(seq(n)) # permutation aleatoire
      sup[i] = mean(x[p[1:(n/2-1)]]) > mean(x[p[(n/2):n]])}
   mean(sup) # frequence des cas ou le premier sous-echantillon est de moyenne empirique superieure au deuxieme
</code>

* Respectez les recommandations usuelles concernant le nombre de chiffres significatifs. Inspirez-vous de la page [http://fr.wikipedia.org/wiki/Chiffre_significatif Wikipédia] consacrée à ce sujet. Ceci s'applique tout particulièrement aux projets impliquant l'analyse de données qui vous sont fournies, avec une certaine précision, et auxquelles vous appliquez des opérations (addition, multiplication, logarithme, ...).

* Respectez les [http://physics.nist.gov/cuu/Units/rules.html conventions de style] en vigueur concernant les unités du système international d'unités. Par exemple, le nom des unités est un nom commun. Même si l'unité dérive d'un nom propre, la première lettre du nom d'une unité est donc toujours une minuscule (contrairement à son symbole) (source : [http://fr.wikipedia.org/wiki/Système_international_d'unités http://fr.wikipedia.org/wiki/Système_international_d'unités]).


[[Category:Première Année|Categories]]