diff --git a/module2/ressources/maintaining_a_journal_fr.org b/module2/ressources/maintaining_a_journal_fr.org index f5c812d5c3a969ad00625ed19edd1e4e5e0a4e5e..f878f11b9d6a4386bc44fbb12b41180c2f20b1c9 100644 --- a/module2/ressources/maintaining_a_journal_fr.org +++ b/module2/ressources/maintaining_a_journal_fr.org @@ -1,189 +1,230 @@ # -*- mode: org -*- -#+TITLE: FIXME Maintaining a journal +#+TITLE: Tenir un journal à jour #+DATE: June, 2018 #+STARTUP: overview indent #+OPTIONS: num:nil toc:t #+PROPERTY: header-args :eval never-export -* Table of Contents :TOC: -- [[#some-examples-of-labbooks-provided-for-inspiration][Some examples of LabBooks provided for inspiration]] -- [[#how-to-report-efficiently-by-martin-quinson][How to report efficiently (by Martin Quinson)]] - - [[#reporting][Reporting]] - - [[#reporting-logistics][Reporting Logistics]] - - [[#reporting-document-organization][Reporting Document Organization]] - -* Some examples of LabBooks provided for inspiration -Since a few years, we systematically require any or our students to -have a laboratory notebook in org-mode. Most of the time, they start -in private repositories but often end up being fully opened. Here are -a few ones: - -- Luka Stanisic (a former PhD student advised by Arnaud Legrand) starting - using this methodology during his Msc and developed further - throughout his PhD. Part of his [[http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf][PhD thesis]] was actually about - designing a methodology for reproducible experiments in large scale - distributed systems. You may want to have a look at [[http://starpu-simgrid.gforge.inria.fr/][his postdoc - LabBook]] and to the [[https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org][report of Léo Villeveygoux]] whom he advised. -- Tom Cornebize is currently a PhD student advised by Arnaud Legrand - and during his MSc, he also heavily [[https://github.com/Ezibenroc/simulating_mpi_applications_at_scale][loged his activity on Github]]. -- [[https://github.com/schnorr][Lucas Schnorr]]'s students usually also maintain their journal in a - very nice way: [[https://github.com/taisbellini/aiyra/blob/master/LabBook.org][Tais Bellini's BSc.]], [[https://github.com/mittmann/hpc/blob/master/LabBook.org][Arthur Krause's LabBook]], [[http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html][Luca - Nesi's LabBook]]. -- [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][Martin Quinson]]'s students also follow such conventions: - - Ezequiel Torti Lopez, M2R 2014. [[https://github.com/mquinson/simgrid-simpar/blob/master/report.org][Report]], with both the data - provenance and the data analysis included in the appendix. +* Table des matières :TOC: +- [[#1-quelques-exemples-de-cahiers-de-notes-ou-de-laboratoires-pouvant-servir-de-source-dinspiration][1. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration]] +- [[#2-comment-rendre-compte-de-son-activité-efficacement][2. Comment rendre compte de son activité efficacement]] + - [[#le-reporting][Le Reporting]] + - [[#logistique][Logistique]] + - [[#organisation-dun-compte-rendu-dactivité][Organisation d'un compte rendu d'activité]] + +* 1. Quelques exemples de cahiers de notes ou de laboratoires pouvant servir de source d'inspiration +Depuis plusieurs années, nous demandons systématiquement à tout +étudiant travaillant avec nous tenir à jour un cahier de laboratoire, +généralement en org-mode. La plupart du temps, ces documents +commencent à être rédigés dans des dépôts privés mais assez souvent +ils finissent par être complètement ouverts et mis à disposition du +plus grand nombre. En voici quelques-uns: + +- Luka Stanisic (un ancien doctorant d'Arnaud Legrand) a commencé à + utiliser cette méthodologie pendant son stage de M2 et a continué à + l'améliorer pendant son doctorat. Une partie de sa [[http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf][thèse]] a en fait + porté sur la conception d'une méthodologie adaptée à la traçabilité + et à la reproductibilité des expériences sur les plates-formes de + calcul à hautes performances. Vous pourriez donc vouloir jeter un + oeil au [[http://starpu-simgrid.gforge.inria.fr/][cahier de laboratoire tenu pendant son postdoc]] ainsi qu'au + [[https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org][rapport de Léo Villeveygoux]] qu'il a encadré pendant cette même + période. +- Tom Cornebize est actuellement en thèse sous la supervision d'Arnaud + Legrand et comme les autres, pendant son stage de master, il a + également intensément [[https://github.com/Ezibenroc/simulating_mpi_applications_at_scale][pris des notes sur son activité quotidienne et + les a mis à disposition sur Github]]. +- Les étudiants de [[https://github.com/schnorr][Lucas Schnorr]] sont aussi généralement bien formés à + cet exercice de prise de note dans un journal: [[https://github.com/taisbellini/aiyra/blob/master/LabBook.org][Tais Bellini's BSc.]], + [[https://github.com/mittmann/hpc/blob/master/LabBook.org][Arthur Krause's LabBook]], [[http://www.inf.ufrgs.br/~llnesi/memory_report/MemoryReport.html][Luca Nesi's LabBook]]. +- Ceux qui travaillent sous la supervision de [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][Martin Quinson]] suivent + des conventions similaires: + - Ezequiel Torti Lopez, pendant son M2 en 2014, a produit un [[https://github.com/mquinson/simgrid-simpar/blob/master/report.org][rapport]] + où les données, leur provenance et leur analyse étaient fournies + dans l'annexe. - Betsegaw Lemma, M2R 2017. [[https://github.com/betsegawlemma/internship/blob/master/intern_report.org][LabBook]] - - Gabriel Corona, engineer on SimGrid, 2015-2016. [[https://github.com/randomstuff/simgrid-journal/blob/master/journal.org][Journal]], [[http://www.gabriel.urdhr.fr/tags/simgrid/][Blog (findings)]]. - - Matthieu Nicolas, engineer on PLM, 2014-2016, [[https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org][Journal]]. - -Org-mode is obviously not the only option and many of our students use -am mixture of org-mode, rstudio and jupyter depending on what is more -convenient. - -* How to report efficiently (by Martin Quinson) -My friend Martin has gathered [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][an excellent compendium of information -and references on his webpage to explain his students what he expects -from them]]. *I'll therefore simply paraphrase him here* with the most -important aspects related to reporting but feel free to read [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][the -original version]]: -** Reporting -I ask you to write a little reporting regularly. Depending on the -situation, it may be every day, every week or every month. In any -case, your reporting is very important for the following reasons: - -- It forces you to think about what you are doing, which may help you - to unblock your problem by your own. Writing down the problems in a - clear way is often sufficient to see the solution appearing. -- It helps me following your progress even between the meetings. I - cannot unblock you if I don't detect that you are on a wrong lead or - otherwise blocked. -- It keeps a track of the steps in your work. That's good for the day - where you want to write your final report (even if a final report - should never be presented in the chronological order). That's good - for the next after you who will be supposed to continue you effort, - or to build upon it. -- That person may be yourself (if you go for a PhD program), another - intern, myself or even someone else on the Internet: that's what we - call Open Science, an effort where everyone can build upon the - scientific work of everyone. - -I want you to write your reporting in an org file (yep, you don't have -a choice here). [..] -** Reporting Logistics -Once you're setup with all software installed and somehow configured, -you need to create a reporting file in a place where I can see it and -where it won't get lost if your disk crashes or something. Open a -dedicated git repository (on github, gitorious, gitlab, ...) for -that. After your internship, your report should be archived directly -in the source tree of the software that you are working on, if -any. But having your reporting located in the source tree may -complicate things during your work. - -Yes, it means that your file will be public at some point, but that's -why we call it "Open Science", after all. Also, you should write it in -English if possible. The part of your reporting that is called -"Journal" (see below) may be written in French if you are more -efficient this way but the rest must be in English. Don't make your -tone too formal because the file is public. Make it efficient. Nobody -will ever blame you for the work you did during an internship a long -time ago. If you really want, we can even make this file -anonymous. Just speak to me. - -You want to write your reporting before leaving work. Weekly reporting -should be written on Friday, one or two hours before leaving. That's -the best solution to have a nice week end without thinking about work, -and still lose no information that you would need on Monday morning. -** Reporting Document Organization - -Your reporting document should have four main parts: - -- Findings :: This section summarizes the general information that you - gathered during your work. It is empty at the beginning - of your internship, and gets fleshed with the important - things that you find on your way. That's where - bibliographical information go, for example. But that's - definitely not where TODO notes go (see below). -- Development :: This section presents the technical sides of your - work. Don't write anything in there yet. Put it all - in the Journal part for now. -- Journal :: Describe the day-to-day work done for each period (day, - week or month) of your internship. That's the most - important part of your reporting, and we come back to it - below. -- Conclusion :: That's what you write in the next week of your - internship. You can see it as a letter to the next - guy, explaining the current state of your work, a few - words about its technical organization, and what - should be done next on that topic. Keep this part - highly technical, the overall organization of your - internship will be seen in your final report. - - The Journal part is the only part that you may write - in French on need. You want to add one subsection per - period to your journal. Don't make it too long, or you - would waste time writing long texts that very few will - ever read. Don't make it too short or it will be - impossible to understand it on Monday morning (or - three months after). Finding the good balance is - sometimes difficult, but I will provide feedback on - your first entries, so don't worry. - -Each of section describing a period should contain three subsubsections: -- Things done :: a few words about what you've done. Something like 2 - or 4 items with a few words describing what you've - done. You can omit the title of that section and put - the items directly in the upper section (see the - example below). -- Blocking points and questions :: try to explain clearly the things - that block you or slow you down. If you found the solution - already, then it should be part of the previous subsection (but - you should say a few words nevertheless). Also ask every question - that you may have for me in that section. If the question are - personal (e.g., about the logistics of your internship such as - salary or so), please prefer emails that are not publicly - visible. If this section is empty for a given period, skip it - all together (no empty subsubsections). -- Planned work :: A few items about what you plan to work on during - the next period. - -A template of reporting file is given at the end of this section. This -is just a strong advice: If you really feel better with another file -organization, then give it a try for one period, and ask for my -feedback. I can adapt, and I do not pretend that my advice is the -definitive answer. It's just the result of my experience so far. - -Notice how TODO items are written: they are given as items in the -Planned work sections of the journal. As explained in the -[[http://orgmode.org/manual/Checkboxes.html][documentation]], you simply have to write "[ ]" in front of items that -you plan to do in the future. - -You should add a [1/] on the "Planned work" line, so that emacs keeps -track of what is done and what is still to do. Once they are done, you -type C-c C-C on their lines to change the blank box [ ] into a checked -box [X]. Also, the [1/] will be changed to denote the amount of work -that is still to be done. - -At any point, you can see all ongoing TODO items with the following -keystrokes: "C-c / t". More information on TODOs in orgmode's -[[http://orgmode.org/manual/TODO-basics.html][documentation]]. The important thing here is that most TODO items must -only be written in the /Journal/ part (so that we know when they -occurred). - -*Do not edit past entries of your journal*, unless you have very good -reasons. If you must, make sure that you don't lose information about -the path that you took (remember the Open Science thingy). You should -always *add* information to past entries, such as: + - Gabriel Corona (ingénieur de recherche sur le projet SimGrid, + 2015-2016) maintient également un [[https://github.com/randomstuff/simgrid-journal/blob/master/journal.org][journal]] et un [[http://www.gabriel.urdhr.fr/tags/simgrid/][blog (findings)]]. + - Matthieu Nicolas (ingénieur sur PLM, 2014-2016): [[https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org][Journal]]. + +Org-mode n'est évidemment pas la seule option et il est courant que +nos étudiants et collègues utilisent un mélange d'org-mode, rstudio et +de jupyter selon ce qui est le plus adapté à leurs besoins du moment. + +* 2. Comment rendre compte de son activité efficacement +Mon ami Martin a réalisé [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][une excellente collection d'informations et +de références sur sa page web pour expliquer à ses étudiants ce qu'il +attends d'eux]]. *Je vais donc tout simplement le paraphraser dans cette +section* en rappelant les éléments qui me semblent essentiels (mais je +vous invite à lire [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][l'original]]). +** Le Reporting +Je vous demande de rendre compte de votre activité par écrit, +régulièrement. Selon la situation, cela peut être chaque jour, chaque +semaine ou chaque mois, mais dans tous les cas, votre compte rendu est +essentiel pour les raisons suivantes: + +- Ça vous force à réfléchir à ce que vous êtes en train de faire, à + prendre du recul, ce qui peut vous permettre de résoudre vos + problèmes par vous même. Énoncer clairement votre problème permet + souvent de faire apparaître des solutions. +- Ça m'aide à suivre votre progression et à réfléchir à votre + problème, même entre deux réunions. Je ne pourrai pas vous aider si + je ne sais pas que vous êtes partis dans une mauvaise direction ou + même que vous êtes bloqués avec tel ou tel point technique. +- Ça vous permet de garder une trace de votre travail. C'est très + précieux le jour où vous aurez à écrire votre rapport final (même si + un rapport n'est jamais présenté dans un ordre chronologique). +- C'est aussi précieux pour celui qui viendra après vous et souhaitera + repartir de vos travaux, les poursuivre ou les améliorer. Cette + personne peut d'ailleurs être vous même dans quelques mois (si vous + vous engagez dans une thèse), un autre stagiaire, moi-même ou même + un inconnu à l'autre bout du monde et qui a trouvé vos travaux via + Internet: c'est ce qu'on appelle la science ouverte, un effort + collectif ou chacun peut efficacement s'appuyer sur le travail + scientifique de toute autre personne. + +Je veux que vous écriviez votre compte rendu d'activité dans un +fichier org-mode (et oui, vous n'avez pas le choix! ). [..] +** Logistique +Une fois que vous aurez mis en place et plus ou moins configuré tous +les logiciels dont vous aurez besoin, il vous faudra créer un fichier +dans un endroit auquel je puisse accéder et qui ne sera pas perdu si +jamais votre disque dur est endommagé, que vous vous faites voler +votre ordinateur, ou autre. Pour cela, commencez par créer un dépôt +git (sur github, gitorious, ou gitlab, ...). À la fin de votre stage, +votre rapport devra être archivé directement dans l'arborescence du +logiciel auquel vous avez contribué. Travailler directement dans cette +arborescence pendant votre stage peut cependant être un peu compliqué. + +Mais, oui, cela veut dire que votre journal sera publique à un moment +ou à un autre (après tout, c'est pour ça qu'on parle de science +ouverte). Vous avez donc intérêt à écrire votre rapport en Anglais si +c'est possible. La partie compte-rendu d'activité (votre "journal") +peut être écrite en Français si vous êtes plus efficace ainsi mais le +reste doit être rédigé en Anglais. Pas la peine de prendre un ton trop +formel sous prétexte que le document a vocation à être publique. +Soyez efficace. Personne ne vous tiendra rigueur de ce que vous avez +pu écrire à l'occasion de votre stage il y a de nombreuses années. Si +vous insistez, il est possible d'anonymiser ou de pseudonymiser ce +document, venez m'en parler. + +Enfin, il est important d'écrire votre compte rendu avant de quitter +votre bureau, tant que les choses sont fraîches dans votre esprit. En +plus, cela vous libérera de la charge mentale induite par ce travail +de mémorisation. Si vous décidez de faire un reporting hebdomadaire, +faites le le vendredi, une ou deux heures avant de partir. C'est la +meilleur façon de passer un bon week-end sans avoir à penser à votre +travail et de ne perdre aucune information dont vous pourriez avoir +besoin lundi matin. Même principe si vous faites un reporting +quotidien. +** Organisation d'un compte rendu d'activité +Selon moi, une bonne pratique consiste à structurer votre compte rendu +d'activité de la façon suivante: + +- Résultats :: Cette section résume les informations que vous avez + obtenu à l'occasion de votre recherche. Elle est + généralement vide au début de votre stage et prendra du + volume au fur et à mesure que vous trouvez des + choses. C'est aussi souvent ici qu'atterrissent les + références bibliographiques par exemple mais ce n'est + clairement pas l'endroit où vous stockez votre liste + des choses à faire (TODO). +- Développement :: Cette section présente les aspects techniques de + votre travail. N'écrivez rien ici pour + l'instant. Mettez tout ce que vous collectez dans + la partie Journal. +- Journal :: C'est ici que vous décrivez votre travail au jour le + jour, de façon chronologique (jour, semaine, mois, + ...). C'est la partie la plus importante de votre + reporting et nous y revenons un peu plus bas. +- Conclusion :: C'est la section que vous écrivez la dernière semaine + (ou celle d'après) de votre stage. Vous pouvez la voir + comme une lettre à la prochaine personne expliquant + l'état actuel de votre travail, avec quelques + informations que son organisation technique et ce qui, + selon vous, sont les prochaines choses à faire et + pourquoi. Cette partie peut-être hautement technique, + les tenants et les aboutissants plus globaux de votre + stage étant des considérations qui apparaîtront plutôt + dans votre rapport final de stage. + +La partie Journal est la seul que vous avez le droit d'écrire en +Français si vous êtes plus à l'aise ainsi. Pas la peine de vous +"répandre", vous perdriez votre temps à écrire un long texte que très +peu de personnes seront susceptibles de lire. Ne la bâclez pour autant +car si elle est trop courte elle sera incompréhensible la semaine +d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas +toujours simple mais je vous ferai un retour sur vos premières entrées +donc ne vous inquiétez pas. + +Une bonne habitude consiste à ce que chacune des entrées section +décrivant une période de travail soit structurée de la façon suivante: +- Travail effectué :: quelques mots sur ce que vous avez fait et son + contexte. Cela peut prendre la forme d'une petite liste de 2 à 4 + entrées sur ce que vous avez fait et pourquoi vous l'avez fait. +- Ponts bloquants et questions :: essayez d'expliquer clairement les + points de blocage que vous rencontrez ou bien les points qui vous + gênent et vous ralentissent. Si vous avez finalement déjà trouvé + la réponse à ces problèmes, indiquez leu dans la sous-section + précédente. C'est aussi ici que vous écrirez toute question que + vous aimeriez me poser. Si ce sont des interrogations + personnelles (par exemple sur la logistique de votre stage, le + logement, votre salaire), utilisez plutôt le mail qui restera + privé entre nous (souvenez vous que ce journal a vocation a + devenir un document publique). Si cette section est vide pour une + période donnée, sautez la tout simplement (ne gardez pas de + sous-sections vides). +- Travaux prévus :: Une petite liste détaillant les points auxquels + vous comptez vous attaquer dans la période à venir. + +Vous trouverez à la fin un modèle de compte rendu d'activité. Un +conseil: si vraiment vous vous sentez mieux avec une autre +structuration de document, essayez pour une période donnée et on fera +le point. Je sais m'adapter et je ne prétends pas avoir la science +infuse ni que mes conseils soient la solution ultime et +universelle. C'est juste le résultat de mon expérience jusqu'ici. + +Remarquez comment les entrées commençant par le mot-clé TODO +apparaissent. On le retrouvera typiquement dans les sections "Travaux +prévus" du journal. Comme expliqué dans la [[http://orgmode.org/manual/Checkboxes.html][documentation d'org-mode]], +vous pouvez aussi tout simplement écrire =[ ]= au début de chaque +élément d'une liste de choses que vous avez l'intention de faire. + +Dans ce cas, en rajoutant un [1/] à la fin de la sous-sous-section +"Travaux prévus", Emacs tiendra à jour le compte des choses faites et +qui restent à faire. Une fois que ce qui est décrit dans l'un des +éléments d'une liste est faite, il vous suffit de faire =C-c C-C= sur +cette entrée pour transformer le =[ ]= en une version cochée =[X]=. Le +[1/] sera alors mis à jour pour refléter la quantité de travail +restant. Lorsque tout aura été effectué, le mot-clé TODO passera à +DONE, ce qui procure un incroyable sentiment de satisfaction. :) + +À tout moment, vous pouvez avoir accès à l'ensemble des choses à faire +(TODO) à l'aide du raccourci clavier suivant: =C-c / t=. Vous trouverez +plus d'informations sur les TODOs dans la [[http://orgmode.org/manual/TODO-basics.html][documentation d'orgmode]]. Le +point important à retenir ici est que la plupart des TODO doivent +apparaître dans la partie journal (afin de savoir quand ils se sont +posés). + +*N'éditez jamais les entrées de votre journal a posteriori*, sauf si +vous avez vraiment une très bonne raison. Si cela devait arriver, +assurez vous que vous ne perdez pas d'informations sur ce que vous +avez fait et les choix que vous avez effectués (souvenez vous, science +ouverte, tout ça tout ça). Il faut toujours *ajouter* des nouvelles +informations aux anciennes, par exemple comme ceci: #+begin_src shell :results output :exports both - *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information. #+end_src -The only exception are TODO entries, that should clearly be rewritten -to DONE entries. If you need to adapt your TODO entry (because the -initial goal was poorly stated or otherwise), change the initial entry -from TODO to CANCELED (or check the box after stating in a subitem -that it was not done but canceled, and why), and create a new TODO -entry in the current period section. +La seule exception à cet édition des entrées passées, ce sont les +entrées de type TODO, qui sont dynamiques et ont vocation à être +transformées en entrées de type DONE. Si vous réalisez qu'il est utile +d'adapter une entrée TODO (parce que l'objectif initial a été mal +formulé, est inadapté, que sais je?), faites passer l'entrée d'origine +de TODO à CANCELED (et/ou cochez le =[ ]= en indiquant dans une +sous-entrée que cette tâche n'a pas été faite mais annulée et +pourquoi) et créez une nouvelle entrée TODO dans la section du jour. + #+BEGIN_EXAMPLE * Introduction This file contains the reporting for my beloved internship done on