<h2id="org6a406ba">Some examples of LabBooks provided for inspiration</h2>
<divclass="outline-text-2"id="text-org6a406ba">
<p>
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:
</p>
<ulclass="org-ul">
<listyle="margin-bottom:0;">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 <ahref="http://mescal.imag.fr/membres/luka.stanisic/thesis/thesis.pdf">PhD thesis</a> was actually about
designing a methodology for reproducible experiments in large scale
distributed systems. You may want to have a look at <ahref="http://starpu-simgrid.gforge.inria.fr/">his postdoc
LabBook</a> and to the <ahref="https://framagit.org/lvgx/pfe/blob/master/doc/labbook.org">report of Léo Villeveygoux</a> whom he advised.</li>
<listyle="margin-bottom:0;">Tom Cornebize is currently a PhD student advised by Arnaud Legrand
and during his MSc, he also heavily <ahref="https://github.com/Ezibenroc/simulating_mpi_applications_at_scale">loged his activity on Github</a>.</li>
<listyle="margin-bottom:0;"><ahref="https://github.com/schnorr">Lucas Schnorr</a>'s students usually also maintain their journal in a
very nice way: <ahref="https://github.com/taisbellini/aiyra/blob/master/LabBook.org">Tais Bellini's BSc.</a>, <ahref="https://github.com/mittmann/hpc/blob/master/LabBook.org">Arthur Krause’s LabBook</a></li>
<listyle="margin-bottom:0;"><ahref="https://people.irisa.fr/Martin.Quinson/Research/Students/Methodo/">Martin Quinson</a>'s students also follow such conventions:
<ulclass="org-ul">
<listyle="margin-bottom:0;">Ezequiel Torti Lopez, M2R 2014. <ahref="https://github.com/mquinson/simgrid-simpar/blob/master/report.org">Report</a>, with both the data provenance and the data analysis included in appendix.</li>
Your reporting document should have four main parts:
</p>
<dlclass="org-dl">
<dt>Findings</dt><dd>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).</dd>
<dt>Development</dt><dd>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.</dd>
<dt>Journal</dt><dd>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.</dd>
<dt>Conclusion</dt><dd><p>
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.
</p>
<p>
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.
</p></dd>
</dl>
<p>
Each of section describing a period should contain three subsubsections:
</p>
<dlclass="org-dl">
<dt>Things done</dt><dd>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).</dd>
<dt>Blocking points and questions</dt><dd>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).</dd>
<dt>Planned work</dt><dd>A few items about what you plan to work on during
the next period.</dd>
</dl>
<p>
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.
</p>
<p>
Notice how TODO items are written: they are given as items in the
Planned work sections of the journal. As explained in the
<ahref="http://orgmode.org/manual/Checkboxes.html">documentation</a>, you simply have to write "[ ]" in front of items that
you plan to do in the future.
</p>
<p>
You should add a <code>[1/]</code> 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 <code>[1/]</code> will be changed to denote the amount of work
that is still to be done.
</p>
<p>
At any point, you can see all ongoing TODO items with the following
keystrokes: "C-c / t". More information on TODOs in orgmode's
<ahref="http://orgmode.org/manual/TODO-basics.html">documentation</a>. The important thing here is that most TODO items must
only be written in the <i>Journal</i> part (so that we know when they
occured).
</p>
<p>
<b>Do not edit past entries of your journal</b>, 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 <b>add</b> information to past entries, such as:
</p>
<divclass="org-src-container">
<prestyle="padding-left: 30px; background-color: #f6f8fa;"class="src src-shell">- *edit* This hypothesis does not hold; see the entry of [the day where you found it] for more information.
</pre>
</div>
<p>
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
