Reporting: write the document, not the notebook
Seven sections, blocks poured from the workshop, an automatic journal, and a cross-review by somebody who was not there
Objectives
By the end of this session you will be able to:
- Fill the seven sections of the imposed plan, each answering its own questions
- Pour the right blocks from the workshop, and only the right ones
- Use the automatic journal instead of writing down what you did
- Spot a stale block and refresh it, or freeze it on purpose
- Export and print a report that a non-specialist can read
- Review somebody else's report against a checklist
Prerequisites
- A rakoon-ds account on https://rakoon-ds.apps.way-up.io (free, browser only, nothing to install), and the group join code your instructor gives you
- A recent Chrome, Edge or Firefox. Computation runs either in your own tab (browser engine) or on the server; the header pill tells you which
- The mission for this session, assigned to your group. Open a project, then the Mission button in the workshop header: the panel opens next to Report. Click Check after each step
- One of your own projects from Sessions 2, 4, 7 or 12, with at least three models and three pinned figures
- A partner: the last step is a cross-review
- Transformation, chart and algorithm names come from the rakoon-ds registry and are served in French even when the interface is in English. Every step below gives you the French label you will click and, in
code font, the registry key the mission checks against.
Data
No new data. This session works on a project you already built. If you have to choose, take the one you understand best, not the one with the best score: you will have to defend every sentence.
Timing
The steps below add up to the announced duration. If you fall behind, Step 1 to Step 3 are the ones that must be finished.
| # | What you do | Time |
|---|---|---|
| Step 1 | Audit what you already have | 10 min |
| Step 2 | The seven sections, and the questions they ask | 18 min |
| Step 3 | Pour the right blocks, not all the blocks | 15 min |
| Step 4 | The journal, the lineage, the card | 12 min |
| Step 5 | Read, print, export | 10 min |
| Step 6 | Cross-review | 10 min |
| Total | 75 min | |
Instructions
Step 1: Audit what you already have10 min
- Open your project and the Report panel.
- Expand all seven sections. Count: how many are empty?
- Click Lecture to open the read mode in a new tab. Empty sections are simply not shown, which is exactly how a reader will experience your gaps.
Fill this audit table before writing anything:
| Section | Written? | Blocks poured | What is missing |
|---|---|---|---|
| Question et contexte | |||
| Données | |||
| Exploration | |||
| Préparation | |||
| Modélisation | |||
| Évaluation | |||
| Conclusion et limites |
Step 2: The seven sections, and the questions they ask18 min
The plan is imposed on purpose. Each section carries its guiding questions in grey until you type something. Answer them, do not paraphrase them.
| Section | The questions it asks you |
|---|---|
| Question et contexte | What question is being asked? Who will use the answer? How will you know it worked? |
| Données | Where does the data come from and what is one row? What is the target and why? What is missing? |
| Exploration | Which distributions surprised you? Which variables look related to the target? Missing or aberrant values? |
| Préparation | Which columns were dropped and why? How were missing values handled? Which encoding, which scaling? |
| Modélisation | Which algorithm, and why that one? Which settings did you try? How was the data split? |
| Évaluation | Which metric, and why? Does it beat a simple baseline? Where is it wrong? |
| Conclusion et limites | What can you claim, with what confidence? Which limits, which risks? What would be next? |
Write all seven. Minimum lengths that make a section worth reading: 5 lines for the first, 8 for the data, 8 for the exploration, 10 for the preparation, 8 for the modelling, 10 for the evaluation, 10 for the conclusion.
Markdown works: **bold**, - lists, > quotes, | tables | and titles. The Preview button shows the rendering. Text is saved 0.7 s after you stop typing, and the indicator says Saved.
Step 3: Pour the right blocks, not all the blocks15 min
You never draw in the report. You pour into it what the workshop produced.
| Block | Where the button is | Put it in |
|---|---|---|
| A pinned figure | Explorer, Add to report next to Pin | Exploration |
| The dataset profile | Explorer, Statistics tab | Données |
| A cross-table | Explorer, pivot tab | Exploration |
| Metrics, confusion matrix, ROC, importance | Results screen, Rapport tab | Évaluation |
| The experiment comparison | Results screen, Rapport tab | Modélisation |
| Démarche (lignage), your whole chain drawn | Results screen, Rapport tab | Préparation |
| A free note | Report panel, Add a note | anywhere |
- Pour at most eight blocks. A report with thirty blocks is a dump, not a document.
- Caption every single one. The caption field saves itself. The violet star asks the assistant for a caption; without a Gemini key it tells you how to enable it, and you write your own in ten seconds.
- Reorder with the up and down chevrons. There is no drag and drop, on purpose.
The ROC curve block only appears for binary classification. And a figure pinned through the API rather than through the Add to report button has no PNG capture, so it will be missing from the ZIP export. Use the button.
Step 4: The journal, the lineage, the card12 min
- Click Journal at the top of the report panel. The studio rebuilds the full chronology from the lineage: every dataset loaded, every transformation with its parameters, every training with its algorithm, target, split and main metric, every pinned figure.
- Choose the destination section (Préparation by default, or Modélisation, Données, Conclusion) and click Insérer dans le rapport.
- Now go back to one of your models and click Ré-entraîner. Return to the report: every block that came from that model now carries an orange périmé badge and a refresh arrow.
- Refresh one. Freeze another with the pin icon: a frozen block is never called stale again, even when its source moves.
That badge is the single most useful feature of the report panel. A figure that no longer matches the model it came from is the classic way an honest report becomes a false one, and here it cannot happen silently.
Two things to know: the journal is written in French, server side, because it reuses the transformation descriptions; and the Markdown export uses the French section titles unless someone renamed them. On an English-language course, plan to rename the seven sections once, or to edit the exported file.
Step 5: Read, print, export10 min
- Lecture: the report opens full page as a document. Read it from top to bottom, out loud if you can. Every sentence that you would have to explain in person is a sentence to rewrite.
- Imprimer / PDF: the print dialog. The toolbar, the footer and the monitor pill disappear, block frames fade, and no block is cut across two pages.
- Exporter le rapport: three outputs. Markdown + images (.zip) is the archive; Markdown (.md) is the text alone; Notebook enrichi (.ipynb) is the branch of your choice as a runnable notebook with your report text woven in.
Open the notebook export and look at what it produced. Your click-only chain comes back as Python: that is the answer to anybody who says a no-code tool produces nothing reusable.
Step 6: Cross-review10 min
Swap read-mode links with your partner. Review their report against this checklist and give them the filled list. No score, no opinions, just the boxes.
- Can I tell what question was asked, without reading further than the first section?
- Do I know what one row is?
- Is there a baseline, with a number?
- Is the metric named, and is the choice justified?
- Is there a sentence saying where the model is wrong?
- Does every figure have a caption that says what it shows?
- Is there a limit stated that is not "we would need more data"?
- Is there any number I cannot trace back to something in the document?
- Are there stale blocks?
- Would I sign this?
Then fix your own report from the list you received, and click Check in the mission panel. The mission checks the seven sections for a minimum length: it cannot check whether they are any good. Your partner can.
What you should have
- Seven sections written, each answering its own guiding questions
- Between five and eight blocks poured, all captioned
- The journal inserted, one stale block refreshed, one frozen
- The report read in read mode, exported as ZIP, and exported as a notebook
- A completed review checklist given, and one received and acted on
- The
dep-13mission at 5 / 5
Deliverables
- Mission:
dep-13validated - The report exported as Markdown + images (.zip)
- The review checklist you filled for your partner, and the one you received
Bonus
- Rename the seven sections into English and re-export. Compare with the default export: the titles are only translated when someone renames them.
- Write a Markdown table in the Évaluation section comparing your models, and check that it renders both in the panel and in the export.
- Take the notebook export, run it, and check that the numbers match your report. If they do not, find out why before you blame the export.
Resources
- Session 13 slides (the lecture this practical work follows)
- Course page: both programmes, all fifteen sessions
- rakoon-ds studio
missions/dep-13.json