- [[#some-examples-of-labbooks-provided-for-inspiration][Some examples of LabBooks provided for inspiration]]
- [[#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]]
- [[#how-to-report-efficiently-by-martin-quinson][How to report efficiently (by Martin Quinson)]]
- [[#2-comment-rendre-compte-de-son-activité-efficacement][2. Comment rendre compte de son activité efficacement]]
- 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)]].
- Gabriel Corona (ingénieur de recherche sur le projet SimGrid,
- Matthieu Nicolas, engineer on PLM, 2014-2016, [[https://github.com/MatthieuNICOLAS/PLM-reporting/blob/master/activity-report.org][Journal]].
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 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
Org-mode n'est évidemment pas la seule option et il est courant que
convenient.
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.
* 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
* 2. Comment rendre compte de son activité efficacement
and references on his webpage to explain his students what he expects
Mon ami Martin a réalisé [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][une excellente collection d'informations et
from them]]. *I'll therefore simply paraphrase him here* with the most
de références sur sa page web pour expliquer à ses étudiants ce qu'il
important aspects related to reporting but feel free to read [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][the
attends d'eux]]. *Je vais donc tout simplement le paraphraser dans cette
original version]]:
section* en rappelant les éléments qui me semblent essentiels (mais je
** Reporting
vous invite à lire [[https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/][l'original]]).
I ask you to write a little reporting regularly. Depending on the
** Le Reporting
situation, it may be every day, every week or every month. In any
Je vous demande de rendre compte de votre activité par écrit,
case, your reporting is very important for the following reasons:
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
- It forces you to think about what you are doing, which may help you
essentiel pour les raisons suivantes:
to unblock your problem by your own. Writing down the problems in a
clear way is often sufficient to see the solution appearing.
- Ça vous force à réfléchir à ce que vous êtes en train de faire, à
- It helps me following your progress even between the meetings. I
prendre du recul, ce qui peut vous permettre de résoudre vos
cannot unblock you if I don't detect that you are on a wrong lead or
problèmes par vous même. Énoncer clairement votre problème permet
otherwise blocked.
souvent de faire apparaître des solutions.
- It keeps a track of the steps in your work. That's good for the day
- Ça m'aide à suivre votre progression et à réfléchir à votre
where you want to write your final report (even if a final report
problème, même entre deux réunions. Je ne pourrai pas vous aider si
should never be presented in the chronological order). That's good
je ne sais pas que vous êtes partis dans une mauvaise direction ou
for the next after you who will be supposed to continue you effort,
même que vous êtes bloqués avec tel ou tel point technique.
or to build upon it.
- Ça vous permet de garder une trace de votre travail. C'est très
- That person may be yourself (if you go for a PhD program), another
précieux le jour où vous aurez à écrire votre rapport final (même si
intern, myself or even someone else on the Internet: that's what we
un rapport n'est jamais présenté dans un ordre chronologique).
call Open Science, an effort where everyone can build upon the
- C'est aussi précieux pour celui qui viendra après vous et souhaitera
scientific work of everyone.
repartir de vos travaux, les poursuivre ou les améliorer. Cette
personne peut d'ailleurs être vous même dans quelques mois (si vous
I want you to write your reporting in an org file (yep, you don't have
vous engagez dans une thèse), un autre stagiaire, moi-même ou même
a choice here). [..]
un inconnu à l'autre bout du monde et qui a trouvé vos travaux via
** Reporting Logistics
Internet: c'est ce qu'on appelle la science ouverte, un effort
Once you're setup with all software installed and somehow configured,
collectif ou chacun peut efficacement s'appuyer sur le travail
you need to create a reporting file in a place where I can see it and
scientifique de toute autre personne.
where it won't get lost if your disk crashes or something. Open a
dedicated git repository (on github, gitorious, gitlab, ...) for
Je veux que vous écriviez votre compte rendu d'activité dans un
that. After your internship, your report should be archived directly
fichier org-mode (et oui, vous n'avez pas le choix! ). [..]
in the source tree of the software that you are working on, if
** Logistique
any. But having your reporting located in the source tree may
Une fois que vous aurez mis en place et plus ou moins configuré tous
complicate things during your work.
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
Yes, it means that your file will be public at some point, but that's
jamais votre disque dur est endommagé, que vous vous faites voler
why we call it "Open Science", after all. Also, you should write it in
votre ordinateur, ou autre. Pour cela, commencez par créer un dépôt
English if possible. The part of your reporting that is called
git (sur github, gitorious, ou gitlab, ...). À la fin de votre stage,
"Journal" (see below) may be written in French if you are more
votre rapport devra être archivé directement dans l'arborescence du
efficient this way but the rest must be in English. Don't make your
logiciel auquel vous avez contribué. Travailler directement dans cette
tone too formal because the file is public. Make it efficient. Nobody
arborescence pendant votre stage peut cependant être un peu compliqué.
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
Mais, oui, cela veut dire que votre journal sera publique à un moment
anonymous. Just speak to me.
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
You want to write your reporting before leaving work. Weekly reporting
c'est possible. La partie compte-rendu d'activité (votre "journal")
should be written on Friday, one or two hours before leaving. That's
peut être écrite en Français si vous êtes plus efficace ainsi mais le
the best solution to have a nice week end without thinking about work,
reste doit être rédigé en Anglais. Pas la peine de prendre un ton trop
and still lose no information that you would need on Monday morning.
formel sous prétexte que le document a vocation à être publique.
** Reporting Document Organization
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
Your reporting document should have four main parts:
vous insistez, il est possible d'anonymiser ou de pseudonymiser ce
document, venez m'en parler.
- Findings :: This section summarizes the general information that you
gathered during your work. It is empty at the beginning
Enfin, il est important d'écrire votre compte rendu avant de quitter
of your internship, and gets fleshed with the important
votre bureau, tant que les choses sont fraîches dans votre esprit. En
things that you find on your way. That's where
plus, cela vous libérera de la charge mentale induite par ce travail
bibliographical information go, for example. But that's
de mémorisation. Si vous décidez de faire un reporting hebdomadaire,
definitely not where TODO notes go (see below).
faites le le vendredi, une ou deux heures avant de partir. C'est la
- Development :: This section presents the technical sides of your
meilleur façon de passer un bon week-end sans avoir à penser à votre
work. Don't write anything in there yet. Put it all
travail et de ne perdre aucune information dont vous pourriez avoir
in the Journal part for now.
besoin lundi matin. Même principe si vous faites un reporting
- Journal :: Describe the day-to-day work done for each period (day,
quotidien.
week or month) of your internship. That's the most
** Organisation d'un compte rendu d'activité
important part of your reporting, and we come back to it
Selon moi, une bonne pratique consiste à structurer votre compte rendu
below.
d'activité de la façon suivante:
- Conclusion :: That's what you write in the next week of your
internship. You can see it as a letter to the next
- Résultats :: Cette section résume les informations que vous avez
guy, explaining the current state of your work, a few
obtenu à l'occasion de votre recherche. Elle est
words about its technical organization, and what
généralement vide au début de votre stage et prendra du
should be done next on that topic. Keep this part
volume au fur et à mesure que vous trouvez des
highly technical, the overall organization of your
choses. C'est aussi souvent ici qu'atterrissent les
internship will be seen in your final report.
références bibliographiques par exemple mais ce n'est
clairement pas l'endroit où vous stockez votre liste
The Journal part is the only part that you may write
des choses à faire (TODO).
in French on need. You want to add one subsection per
- Développement :: Cette section présente les aspects techniques de
period to your journal. Don't make it too long, or you
votre travail. N'écrivez rien ici pour
would waste time writing long texts that very few will
l'instant. Mettez tout ce que vous collectez dans
ever read. Don't make it too short or it will be
la partie Journal.
impossible to understand it on Monday morning (or
- Journal :: C'est ici que vous décrivez votre travail au jour le
three months after). Finding the good balance is
jour, de façon chronologique (jour, semaine, mois,
sometimes difficult, but I will provide feedback on
...). C'est la partie la plus importante de votre
your first entries, so don't worry.
reporting et nous y revenons un peu plus bas.
- Conclusion :: C'est la section que vous écrivez la dernière semaine
Each of section describing a period should contain three subsubsections:
(ou celle d'après) de votre stage. Vous pouvez la voir
- Things done :: a few words about what you've done. Something like 2
comme une lettre à la prochaine personne expliquant
or 4 items with a few words describing what you've
l'état actuel de votre travail, avec quelques
done. You can omit the title of that section and put
informations que son organisation technique et ce qui,
the items directly in the upper section (see the
selon vous, sont les prochaines choses à faire et
example below).
pourquoi. Cette partie peut-être hautement technique,
- Blocking points and questions :: try to explain clearly the things
les tenants et les aboutissants plus globaux de votre
that block you or slow you down. If you found the solution
stage étant des considérations qui apparaîtront plutôt
already, then it should be part of the previous subsection (but
dans votre rapport final de stage.
you should say a few words nevertheless). Also ask every question
that you may have for me in that section. If the question are
La partie Journal est la seul que vous avez le droit d'écrire en
personal (e.g., about the logistics of your internship such as
Français si vous êtes plus à l'aise ainsi. Pas la peine de vous
salary or so), please prefer emails that are not publicly
"répandre", vous perdriez votre temps à écrire un long texte que très
visible. If this section is empty for a given period, skip it
peu de personnes seront susceptibles de lire. Ne la bâclez pour autant
all together (no empty subsubsections).
car si elle est trop courte elle sera incompréhensible la semaine
- Planned work :: A few items about what you plan to work on during
d'après (ou trois mois plus tard). Trouver le bon équilibre n'est pas
the next period.
toujours simple mais je vous ferai un retour sur vos premières entrées
donc ne vous inquiétez pas.
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
Une bonne habitude consiste à ce que chacune des entrées section
organization, then give it a try for one period, and ask for my
décrivant une période de travail soit structurée de la façon suivante:
feedback. I can adapt, and I do not pretend that my advice is the
- Travail effectué :: quelques mots sur ce que vous avez fait et son
definitive answer. It's just the result of my experience so far.
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.
Notice how TODO items are written: they are given as items in the
- Ponts bloquants et questions :: essayez d'expliquer clairement les
Planned work sections of the journal. As explained in the
points de blocage que vous rencontrez ou bien les points qui vous
[[http://orgmode.org/manual/Checkboxes.html][documentation]], you simply have to write "[ ]" in front of items that
gênent et vous ralentissent. Si vous avez finalement déjà trouvé
you plan to do in the future.
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
You should add a [1/] on the "Planned work" line, so that emacs keeps
vous aimeriez me poser. Si ce sont des interrogations
track of what is done and what is still to do. Once they are done, you
personnelles (par exemple sur la logistique de votre stage, le
type C-c C-C on their lines to change the blank box [ ] into a checked
logement, votre salaire), utilisez plutôt le mail qui restera
box [X]. Also, the [1/] will be changed to denote the amount of work
privé entre nous (souvenez vous que ce journal a vocation a
that is still to be done.
devenir un document publique). Si cette section est vide pour une
période donnée, sautez la tout simplement (ne gardez pas de
At any point, you can see all ongoing TODO items with the following
sous-sections vides).
keystrokes: "C-c / t". More information on TODOs in orgmode's
- Travaux prévus :: Une petite liste détaillant les points auxquels
[[http://orgmode.org/manual/TODO-basics.html][documentation]]. The important thing here is that most TODO items must
vous comptez vous attaquer dans la période à venir.
only be written in the /Journal/ part (so that we know when they
occurred).
Vous trouverez à la fin un modèle de compte rendu d'activité. Un
conseil: si vraiment vous vous sentez mieux avec une autre
*Do not edit past entries of your journal*, unless you have very good
structuration de document, essayez pour une période donnée et on fera
reasons. If you must, make sure that you don't lose information about
le point. Je sais m'adapter et je ne prétends pas avoir la science
the path that you took (remember the Open Science thingy). You should
infuse ni que mes conseils soient la solution ultime et
always *add* information to past entries, such as:
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
#+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.
- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
#+end_src
#+end_src
The only exception are TODO entries, that should clearly be rewritten
La seule exception à cet édition des entrées passées, ce sont les
to DONE entries. If you need to adapt your TODO entry (because the
entrées de type TODO, qui sont dynamiques et ont vocation à être
initial goal was poorly stated or otherwise), change the initial entry
transformées en entrées de type DONE. Si vous réalisez qu'il est utile
from TODO to CANCELED (or check the box after stating in a subitem
d'adapter une entrée TODO (parce que l'objectif initial a été mal
that it was not done but canceled, and why), and create a new TODO
formulé, est inadapté, que sais je?), faites passer l'entrée d'origine
entry in the current period section.
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
#+BEGIN_EXAMPLE
* Introduction
* Introduction
This file contains the reporting for my beloved internship done on
This file contains the reporting for my beloved internship done on
