Elements visuels

Tu as très probablement des concepts des types suivants à expliquer.

1. des flux de données
2. des architectures logicielles
3. des protocoles de communication
4. des interfaces de logiciels
5. des diagrammes de classes, de composants ou de séquence,
6. des plans de communication réseau
7. ...

Au lieu de passer de longues pages à expliquer, rends tes concepts visuels avec des captures d'écrans, des schémas ou encore des extraits de code ! La qualité et l'importe des éléments visuels dans le rapport est souvent sous-estimé, alors qu'ils rendent la lecture et compréhension beaucoup plus agréable. Cette page te donne plein d'astuces pour augmenter la qualité du rendu final.

Optimise le ratio !

Tout élément visuel doit idéalement être optimisé pour s'afficher de manière la plus lisible dans la contrainte du format imposé. Le format A4 vertical impose que la largeur de l'image sera restreinte et qu'il est préférable d'agrandir le cadrage d'une image verticalement.

Pour les slides, le ratio étant 16:9 ou 4:3 (donc plus large horizontalement), c'est l'inverse ! Il faut chercher à étendre le contenu en largeur et non en hauteur.

TODO exemple de problème et solution sur le ratio

Format vectoriel

Pour assurer la meilleure qualité d'affichage et de lecture, privilégie toujours les formats vectoriels (SVG ou schémas exportés en PDF) aux images bitmaps (PNG, JPG, WEBP, ...). Ce choix est surtout fait au moment d'exporter des illustrations ou schémas créé dans Inkscape, DrawIO, Excalidraw ou d'autres logiciels.

Un avantage insoupçonné du format SVG, grâce à sa nature textuelle est la possibilité d'appliquer certaines modifications à la main directement, sans devoir recréer les conditions de la capture. Dans le cas, suivant, il était utile de traduire un commentaire vers le français. Il a été possible de corriger le texte affiché directement sans nécessiter une regénération.

- <text x="-1.2384615" y="13.345898">// Basic MCQ exo<tspan/>
+ <text x="-1.2384615" y="13.345898">// Exercice basique de choix multiple<tspan/>

Captures d'écran

Il est fréquent d'avoir des images de mauvaises qualité à cause d'une mauvaise technique de capture. La résolution d'une capture d'écran étant définie par le nombre de pixels de la zone choisie, une petite zone créera une petite image. Une petite image affichée en petit peut être acceptable, mais un petit zoom ou un agrandissement rendra très flou son contenu.

Il vaut la peine de s'assurer d'avoir une résolution légèrement plus grande que nécessaire. Le conseil pour éviter ce problème est de zoomer un maximum dans le contenu que tu veux capturer qu'il prenne le plus de largeur possible sur l'écran.

Captures d'écran de page web

Tente cette extension https://addons.mozilla.org/en-US/firefox/addon/svg-screenshots

TODO: démo d'un site connu incluant une image.

Images

#figure(
  image("diagrams/training.svg"),
  caption: [Training UI],
)<diagram-training>

#figure(
  image("../imgs/rustlings-demo.png", width: 80%),
  caption: [Rustlings interface with a beginner Rust exercise],
)<rustlings-demo>

Morceaux de code

Quand tu inclus un morceau de code, tu peux tout à fait le simplifier (et l'indiquer) pour aider un·e lecteur·ice à se concentrer sur ce que tu cherches à montrer. Pour les personnes qui ne seraient pas familière avec le language que tu utilises, il est peu être très utile d'ajouter quelques commentaires supplémentaires.

#figure(
   ```rust
   ```
  caption: [],
)<rustlings-demo>

Inclure des codes ou données externes

Certaines morceaux de code ou fichiers de données peuvent être mis à jour durant le projet ou sont générés par des automatisations. Au lieu de les copier coller dans le code comme ceci ...

#figure(
   ```json
   {
     "type": "StartSession",
     "content": {
       "name": "PRG2 Jack",
       "group_id": "https://github.com/prg2/prg2.git"
     }
   }
   ```
  caption: [Action `StartSession` servant à démarrer une nouvelle session avec un nom et un groupe.],
)<action-startsession>

et de risquer d'oublier de les mettre à jour s'il change, il est plus simple de les inclure dynamiquement en créant un bloc de code avec #raw et #read.

#figure(
  raw(block: true, lang: "json", read("messages/Action-StartSession.json")),
  caption: [Action `StartSession` servant à démarrer une nouvelle session avec un nom et un groupe.],
)<action-startsession>

Légendes

Les légendes peuvent être définies sur les #figure en Typst, dans le champ caption.

#figure(
  ```rust
  fn main() {
      println!("Hello, world!");
  }
  ```,
  caption: [Hello world en Rust],
)<hello-world>

Il est parfois plus joli de forcer certaines retours à la ligne (avec \ en Typst) pour que la légende ne soit pas beaucoup plus large que l'image, ou que le texte sur une ligne ne soit pas beaucoup plus court que sur une autre. L'exemple suivant le démontre, avec le comportement par défaut à gauche, puis l'ajustement à droite.

En corrigeant simplement en intégratn un retour \ après au milieu du texte, la mise en page rendu mieux.

  caption: [L'exemple lance la compilation du programme, \ lance le binaire généré puis joue 2 coups du TicTacToe.],

Création de schémas

Les schémas prennent du temps à inventer, créer, affiner, arranger et exporter. Un bon schéma peut vraiment apporter énormement à la compréhension, s'il est bien conçu. Tout le challenge est d'arriver à exprimer un concept sans rendre le schéma imense ou illisible, avec la bonne quantité de texte et les bons verbes.

Exemple de maturation des schémas

Cet exemple à pour but de montrer le bénéfice des feedbacks et de techniques pour améliorer un schéma de manière itérative. Le but est de montrer les différents composants d'un serveur WebSocket (pour Delibay), avec les différents threads virtuels et leur communication. On y voit aussi les clients avec deux rôles différents (orange = leader, noir = follower). Les différentes couleurs des flèches ont volontairement été attribuée pour visuellement séparer le contenu des communications, ce qui s'est avéré pour référencer les groupes de flèches dans le texte explicatif.

La première version acceptable du schéma est la suivante. Le retour a été que le schéma était trop lourd à lire au vu du nombres d'éléments.

Une deuxième itération a simplement retiré les éléments dupliqués qui servaient à montrer

Une troisième itération a permis de simplifier encore certains texte et surtout utiliser la technique de l'empilement. Sa force est de continuer de montrer la multitude d'éléments de même type, en prenant une place minimum et en réduisant le nombre de flèches.

Conclusion: montre tes schémas à tes collègues pour voir si le schéma seul est assez clair et affiner tes légendes, flèches, la disposition. Prends inspiration de cette technique d'empilement.

Diagrammes UML

PlantUML peut être d'une grande aide pour générer ou créer des graphiques.

Automatisations de l'export de schémas

TODO: implémenter un système générique d'export automatisé de schémas Excalidraw, PlantUML,