Rapport

Formats de rédaction

Le format a son importance pour l'expérience de rédaction et la mise en page. Il est pénible de perdre du temps sur des détails de mise en page quand on est dans le rush de finir un gros morceau de rapport avant un rendu.

3 formats sont bien supportés: Word, Latex et Typst. Le document doit contenir un certain nombre de sections définis dans les directives de TB TIC. Ces sections ont généralement été reprise dans les templates proposés pour faciliter la rédaction.

Templates de GAPS

Templates Typst

Il existe également un template Typst qui n'est pas officiel mais est tout à fait adapté.

Quel format choisir ?

Il est possible d'utiliser directement l'option avec laquelle tu es le plus à l'aise. Je profite de cette section pour te partager mon avis complètement subjectif sur la question, en faveur de Typst qui me parait produire la plus belle qualité de document pour un TB qui inclut et mentionne du code. Mon biais vers les solutions libres et textuelles, a rendu l'option Word très peu attractive. Il en reste que chaque solution garde ses avantages et inconvénients et qu'aucune n'est parfaite.

Il se peut que Word soit la solution la plus comfortable par défaut mais ne soit pas la plus adaptée à la rédaction d'un TB.

Ca fonctionne bien Word, pourquoi pas Word ???

Le format de fichier est binaire ce qui rend difficile son usage dans Git puisque les différences commitées ne sont pas visibles. Il n'est pas possible de commiter une partie des modifications et de supprimer le reste, tu es à la merci de l'historique du ctrl+z qui reste limité à la dernière ouverture du fichier.
Le format de fichier est propriétaire. Quand tu quitteras la HEIG-VD tu n'auras peut-être plus accès à Word. Il existe LibreOffice qui permet d'ouvrir les .docx mais seul Word ne peut les ouvrir avec 100% de chance d'avoir tous les éléments en place, à commencer par les polices et la mise en page. Au contraire, les fichiers textes seront toujours ouvrables et réutilisables.
La mise en page gérées avec des clics dans tous les sens est pénible. Et contrairement au Markdown, Typst et Latex ont des options avancées de mise en page, ce qui demande de s'y familiariser un peu mais peut faciliter la rédaction.
Pas de support des commentaires, en incluant des TODOs, des questions à poser, ou d'autres notes utiles pour la rédaction. Ces notes risquent de se retrouver dans le rendu final si tu oublies de les retirer. En Latex et Typst, les commentaires sont supportés et permettent ce genre de note personnel.
Ecrire en texte justifié et voir le texte se décaler bizarrement en cours d'écriture perturbe la rédaction
Word ne supporte vraiment pas bien l'intégration de morceau de code en bloc ou à l'intérieur d'une ligne. Faire des screenshots de son IDE qui ne sont pas sélectionnables et ni facilement modifiables n'est pas du tout pratique.
Il n'est pas possible de découper la rédaction en plusieurs fichiers pour se concentrer sur une seule partie et éviter de scroller des kilomètres de page pour arriver au tout début. En Latex et Typst, les chapitres sont définis dans des fichiers dédiés.
Il n'est pas possible de charger dynamiquement des fichiers externes comme de morceau de code et de s'assurer ainsi qu'ils sont toujours à jour. Pour les schémas développés dans d'autres logiciels et exporté en PNG sur le disque, il y a toujours le risque d'oublier de remettre à jour la copie dans le document. Cela est très pratique lorsqu'un fichier est utilisé dans le rapport, mais aussi l'affiche ou la présentation, pour s'assurer que le même fichier est utilisé et reste à jour. En Latex et Typst il est possible de faire ceci et cela permet d'avoir

Je ne connais pas Latex ni Typst, quels sont les points communs et différences ?

Latex et Typst demandent tous deux une compilation du document vers le format PDF. Des fichiers .tex ou .typ permettent de décrire le contenu. Un système de plugin permet dans les deux systèmes d'ajouter des fonctionnalités supplémentaires bien pratiques.

Les 2 options sont éditables localement, à condition pour Latex d'avoir une distribution Latex qui permet de compiler un document, ou d'avoir le CLI Typst. Elles sont également éditables en ligne si la collaboration est importante, sur des services tels que Overleaf pour Latex ou typst.app pour Typst.

Pour être pleinement transparent, je n'ai jamais utilisé Latex, en dehors d'expressions de math.

Pour un usage local, une distribution Latex est beaucoup plus lourde que le CLI Typst. Le CLI Typst 0.13.1 fait environ 42MB tandis que la distribution TeX Live pèse 6GB ! source
La vitesse de compilation est bien différente. Typst est écrit en Rust et la différence de vitesse est majeure. En plus de la compilation rapide de PDF, il est aussi possible d'avoir un preview avec rafraichissement instantané à chaque caractère tapé, une fois l'IDE configuré pour afficher ce preview.

TODO: faire un benchmark du template vide et rempli et reporter les résultats ici.
Typst me paraît beaucoup plus concis et facile à écrire que Latex. Voici quelques exmples:
- Du texte en gras ? Tu préfères \textbf{important} en Latex ou *important* en Typst ?
- Une liste à puce ?
  - En Typst, c'est comme en Markdown, un élément par ligne démarré par - .
  - En Latex, il faut démarrer la liste par \begin{itemize}, puis ajouter \item en début de chaque ligne, puis finalement fermer la liste \end{itemize}. Même les IA sont capables de les rédiger à notre place, je trouve que cela
- Un bloc de code ?
  - En Typst, toujours comme en Markdown, simplement
```
```python
    print("Hello world")
```
```
    et le bloc est nativement colorisé.
  - En Latex, avec le package minted pour avoir des couleurs
```
\documentclass{article}
\usepackage{minted}
\begin{document}
\begin{minted}{python}
print("Hello world")
\end{minted}
\end{document}
```
- Une image ?
  - En Typst, une fonction #image est à disposition, en voici un exemple qui inclut test.png
```
#image("test.png", width: 80%)
```
    Pour un SVG, il suffit de l'inclure comme au dessus.
  - En Latex, ce n'est pas supporté nativement (!) il faut utiliser un plugin pour ça et c'est notamment plus verbeux.
```
\usepackage{graphicx}

\begin{figure}[ht]
    \includegraphics[width=0.8\textwidth]{test.png}
\end{figure}
```
    TODO: checker ce bout généré par Copilot. c'est valide ? j'ai retiré le \centering. Pour un fichier SVG c'est un peu plus compliqué...

Okay mais quelles sont les limites de Typst alors ?

Des issues sur le repos sont mentionnées dans ce post Reddit: Why I use LaTeX instead of Typst - Reddit
Des limitations sont données dans cette section du Guide for LaTeX users de Typst

Stratégies de rédaction

Un travail de Bachelor est loin d'être dans la même difficulté de rédaction d'un rapport de laboratoire. Le niveau de langue, la tolérance aux typos, le contexte à apporter, la clarté du texte, le formalisme et la bibliographie, deviennent tout d'un coup des critères majeurs de qualité du document.

Cette section documente quelques points à faire attention.

Le public cible - A qui s'adresse ton rapport ?

c'est bon mon prof il connait déjà la techno X, je vais pas réexpliquer ce que c'est dans mon rapport, ça va l'ennuyer...

et tu oublies déjà l'expert·e, qui a peut-être moins de contexte en tête. Et aussi tu oublies tous les gens qui pourraient être intéressés plus tard par ton sujet mais qui n'ont pas connaissance de ton langage, de ton environnement, de tes projets passés, des problèmes que tu as rencontrés, ...

Quel est le public cible ? Uniquement les 2 personnes qui évaluent ? Est-ce qu'on écrit aussi pour qu'il soit publié plus tard ? Qui pourrait le relire ?

Une approche possible que Bertil m'avait conseillé est de dire: Le public cible est tout ingénieur·e en informatique, qui a déjà touché à quelques langages de programmation mais pas forcément celui que j'utilise (le Rust dans mon cas).

Que doit contenir le rapport intermédiaire

Est-ce que c'est okay de laisser plein de TODOs sur les sections qui ont été ?

Faire la chasse aux typos

Il est fréquent de vite passer plusieurs heures le jour d'un rendu à "juste" corriger des tonnes et des tonnes de fautes d'orthographe, d'accord au pluriel, de phrases non terminées ou de certaines formulations répétitives. Au lieu de relire manuellement tout seul, c'est indispensable de s'aider d'outil spécialisé sur le sujet.

TODO more if BRE does it

Gestion optimale de la bibliographie

La gestion de la bibliographie consiste en 2 phases.

Récupérer toutes les métadonnées nécessaires pour chaque oeuvre à citer.
Puis exporter cette liste dans le standard de formattage imposé (ordre des valeurs, majuscules, guillemets, etc).

La première prend du temps et la deuxième est quasiment automatique.

Comment bien citer ?

Questions de citations avancées

TODO à résoudre

questions bibliography comment gérer les "et contributeurs" dans la norme ISO 630 comment gérer quand l'auteur est une organisation quand ya le même lien avec 2 sections différentes, 2 entrées ou pas ??

Conversion de BibTex vers Hayagriva

https://jonasloos.github.io/bibtex-to-hayagriva-webapp/

Comment optimiser la création de la bibliographie au fur et à mesure ?

Bonne question, j'y réfléchis encore...

structure

attention à ne pas mapper sans le vouloir la structure ou le déroulement du travail à la structure des pargraphes ou du document.

astuce de backtick -> permet d'éviter une certaine confusion quand man bash -> "wait waits for all running..." to speak about the wait keyword. avoid mixing