Introduction
La mise en œuvre du programme HNSO implique la production de données dans toutes ces formes : documents textes, codes, présentation, schémas, etc. sur une longue période temporelle. Il est donc essentiel d’établir un processus de travail afin de pouvoir gérer et de préserver l’ensemble de ces données en respectant le cycle de vie des données (figure 2.1). Un processus centralisé avec des outils et logiciels communs permettra de produire des données de qualité (métadonnées et formats définis), de pouvoir les déposer dans des lieux de stockage sécurisés pour que l’ensemble de l’équipe puisse les localiser facilement et de les préserver. Ce chapitre offre une proposition de guide ou de modèle de travail collaboratif pour ce type de projet incluant une boîte à outils et basé sur les méthodes agiles. Il est le reflet des pratiques transparentes, reproductibles et évolutives mises en œuvre dans le programme HNSO alimentées par une veille régulière des technologies de gestion de projets informatiques et documentaires.
[Cycle de vie des données, inspiré de DoRANum (2021)]
Les outils numériques
Le projet ISIDORE et NAKALA pour la Science Ouverte qui est l’un des livrables du programme HNSO est construit dans un environnement de travail facilitant l’échange et la communication au sein d’une équipe de travail. Il est basé sur de nombreux outils listés dans le tableau suivant (tableau [2.1][1] ) :
Nom de l’outil | Fonction | |
---|---|---|
HedgeDoc | Prise de notes collectives pendant les réunions | |
Overleaf/LaTeX | Rédaction des documents scientifiques | |
Zotero | Gestion des références bibliographiques | |
GitLab | Dépôt et édition des fichiers du projet | |
Kanboard | Gestion de projet, planification | |
Liste de diffusion | Communication interne | |
Sharedoc | Archivage des documents |
Les plateformes de dépôt
GitLab
Le projet a intégré l’usage de Gitlab1 au cœur de son fonctionnement, assurant à la fois la gestion du projet, le stockage et le versionning des documents produits par les équipes, mais aussi l’organisation formelle de la réflexion collective.
Gitlab implémente le protocole [Git]2, pensé initialement pour le partage et le versionning de [code informatique]. Mais les principes qui régissent le protocole d’échange et de synchronisation de fichiers fournissent en fait une excellente base à l’écriture collaborative de textes discursifs, et à fortiori à l’édition collaborative de documents basés sur des formats Plain/Text.
Par ailleurs, les fonctionnalités communautaires de la plateforme Gitlab viennent outiller le protocole déjà collaboratif dans le sens d’une dynamique collective centrée sur la production de connaissances, entendues ici comme une accumulation raisonnée de diverses écritures : code, données, texte encodé, etc. (voir la section [[sec:gitlab]][2] pour une présentation détaillée).
Kanboard HNSO
Le kanboard HNSO4 (Figure [2.2]) est organisé en 2 blocs principaux :
- un bloc dédié à l’organisation et la gestion courante du projet ;
- un bloc dédié au brainstorming autour des chantiers du projet.
Organisation et gestion courante du projet
Ce bloc (partie gauche du kanboard) est divisé en 4 colonnes suivant une logique chronologique correspondant à la méthode de gestion de projet KANBAN :
- Vrac : boîtes à idées ;
- Prêt : tâches à réaliser mais encore à maturer avant d’être lancées ;
- A faire : tâches prêtes à être réalisées ;
- En cours : tâche en cours de réalisation ;
- Terminé : tâches terminées.
Pour améliorer la compréhension du kanboard, des libellés (tags) peuvent être ajoutés lors de la création d’une tâche. Sur la vue « Tableau », les libellés s’affichent en bas à gauche de la tâche sous forme d’une vignette colorée. S’il n’existe pas de libellés concernant un sujet, il faut contacter l’administrateur du kanboard pour ajouter ce sujet.
Il est aussi possible d’ajouter une catégorie sur la tâche. Celle-ci s’affiche en haut à droite des tâches sur la vue Tableau.
Brainstorming chantiers du projet
Ce bloc (partie droite du kanboard) est divisé en 4 colonnes correspondant aux 4 chantiers HNSO :
- Interconnexion ISIDORE/NAKALA ;
- Évolution ISIDORE/NAKALA ;
- Exploitation ISIDORE/NAKALA ;
- Formation et accompagnement ;
Il n’y a pas de logique chronologique puisqu’il s’agit d’un bloc à idées. Chaque tâche créée correspond à une idée. Il est recommandé de coloriser la tâche en gris clair, d’ajouter une catégorie (numéro du chantier correspondant) ainsi qu’un ou plusieurs libellés (documentaire, informatique et développement, scientifique, autre).
La personnalisation par l’ajout des libellés, couleurs et catégories a pour objectif de faciliter l’organisation du kanboard et de favoriser un meilleure collaboration.
Plateforme Zotero
Il est recommandé de partager les références des ressources qui pourront alimenter le programme HNSO ou générer des discussions dans l’équipe. Il est aussi recommandé d’y enregistrer toutes les références qui sont utilisées dans les rapports du projet afin de favoriser une meilleure collaboration dans l’équipe et de créer des bibliographies automatiques à insérer dans les rapports.
Types et nomenclature des documents et livrables
Tout au long du programme HNSO, différents documents et fichiers seront produits :
- Notes et compte-rendus de séminaires ;
- Rapports scientifiques ;
- Rapports internes ;
- Preuves de concepts ;
- Codes ;
- etc.
Des règles de nommage des fichiers (Tableau [2.2][3]) ont été établies pour une organisation plus harmonieuse et faciliter la recherche des documents.
Type de fichier | Format de fichier | Règles de nommage |
---|---|---|
Notes collaboratives HNSO | markdown (.md) | Date_Point-HNSO |
CR séminaires | markdown (.md) et pdf | Date_CR-séminaire-XX |
Rapports scientifiques | LaTeX et pdf | Nom_et_al_Date_Titre |
Rapports internes | LaTeX et pdf | Nom_et_al_Date_Titre |
Documents de séminaires
Les séminaires HNSO sont des réunions de travail et d’information régulières dont le but est de réunir l’ensemble des collaborateurs du projet afin de faire un point d’avancement du projet. Chaque séminaire possède un ordre du jour précis communiqué en amont de la réunion. Les documents produits par les séminaires sont de deux types :
- Les prises de notes lors de la réunion grâce à l’éditeur de notes collaboratives disponible sur la plateforme HedgeDoc. Ce pad au long court est unique et doit être utilisé pour toutes les réunions de séminaires, incluant aussi d’autres types de réunions de travail du programme HNSO. A la fin de chaque réunion, les notes du jour doivent être extraites en format [markdown] et déposées dans le GitLab ;
- Un compte-rendu synthétique à partir des notes collaboratives à
rédiger en markdown et à déposer dans le même dossier
que les notes du séminaire correspondant, dans le GitLab. Le
compte-rendu est ensuite archivé au format pdf dans le dossier Sharedoc
du HN Lab (figure [2.3])
Des modèles au format markdown spécifient les normes d’écriture de ces deux documents incluant les éléments obligatoires et sont téléchargeables à partir du Gitlab.
---
title: HNSO#N
date: AAAA-MM-JJ
---
Participant.e.s : Initiales
# Seminaire HNSO #N - Date
**ODJ:**
1. Point 1
2. Point 2
3. Point 3
4. Point 4
## Introduction
## Section 1
## Section 2
## Section N
## Synthese
## TCHAT
title: Compte-Rendu de seminaire
date: AAAA-MM-JJ
---
# Programme HNSO : CR seminaire de travail
| Date | JJ mois AAAA, hh-hh|
| :------- | :------- |
| Present.e.s| Prenom Nom, Prenom Nom, etc.|
| Excuse.e.s | Prenom Nom, Prenom Nom, etc.|
## Ordre du jour
1. Point 1
2. Point 2
3. Point 3
4. Point 4
## Introduction
## Section 1
### 1) Sous-Section
### 2) Sous-Section
### 3) Sous-Section
### 4) Sous-Section
## Section 2
### 1) Sous-Section
### 2) Sous-Section
### 3) Sous-Section
### 4) Sous-Section
## Section N
## Conclusion
Rapports scientifiques
Les rapports scientifiques sont des documents qui ont vocation à être publiés sur les plateformes ZENODO5 et HAL6 (Figure [2.4]). Ils sont rédigés en [LaTeX]7 via l’éditeur en ligne Overleaf8 ou via un éditeur local. Pour participer à leur édition, ils sont disponibles soit sur la plateforme Overleaf (demander à être contributeur auprès des administrateurs) ou sur le GitLab HN. Pour des raisons d’ordre informatique liées au protocole GitLab (voir section [2.10]), les documents crées sur Overleaf sont stockés sur le GitLab du HN Lab. Ils doivent aussi être conservés en format .pdf sur ShareDoc. Pour créer un rapport scientifique, il est nécessaire de suivre le modèle en code Latex disponible sur le Gitlab.
Rapports internes
Les rapports internes sont des documents qui ont vocation à
transmettre des informations aux membres du projet ; ils ne sont pas
publiés. Ils sont rédigés en LaTeX via l’éditeur Overleaf ou via un
éditeur local et conservés en .pdf sur ShareDoc (figure [2.5]). Pour
créer un rapport interne, il est nécessaire de suivre le template Latex
disponible sur le Gitlab de HNSO. Parmi ces rapports internes, les
rapports de synthèse sont des jalons qui résument l’activité de l’équipe
sur les 6 derniers mois et la planification des travaux sur les 6
prochains mois (figure [2.6]).
Ouvrage du projet ISIDORE et NAKALA pour la Science Ouverte
Dans une perspective réflexive (Perrenoud 2001; Clerc et Agogué 2014), toutes les activités entreprises dans le projet ISIDORE et NAKALA pour la Science Ouverte sont documentées dans un objet documentaire polymorphe. D’une part, dans ce document rédigé avec Latex qui a vocation a être publié et diffusé sous la forme d’une publication qui se rapproche d’un objet imprimé. D’autre part, sous la forme d’une publication Web offrant un parcours de lecture plus fluide. Ces deux objets sont synchrones, l’objet Web étant généré automatiquement avec le convertisseur [Pandoc]9 à partir des sources Latex de l’ouvrage.
Tutoriels
Convertir un document markdown en pdf ou LaTeX
Il est possible d’éditer les rapports au format makdown (.md) puis de les convertir en pdf ou LaTeX via le convertisseur Pandoc10. Pour cela, il faut installer les packages pandoc et xelatex sur votre machine. Les deux lignes de commande sont les suivantes :
pandoc --pdf-engine=xelatex document.md -o document.pdf
pandoc --pdf-engine=xelatex document.md -o document.tex
Il est possible d’ajouter un template, disponible sur le Gitlab HNSO,
déjà paramétrée en ajoutant l’option
--template=templatepandoc-HNSO.tex
au code ci-dessus :
pandoc --pdf-engine=xelatex --template=templatepandoc-HNSO.tex document.md -o document.pdf
pandoc --pdf-engine=xelatex --template=templatepandoc-HNSO.tex document.md -o document.tex
Synchronisation de la plateforme Overleaf et du GitLab
La plateforme d’édition en LaTeX Overleaf permet de synchroniser avec un dépôt GitLab les documents créés au cours du projet. Cette synchronisation doit être réalisée par l’administrateur du compte Overleaf. Elle a pour but de dupliquer chaque document sur les deux plateformes et de pouvoir réaliser les mises à jour essentielles lorsque plusieurs personnes travaillent sur un même document. Un document Overleaf correspond à la création d’un répertoire sur le GitLab. L’objectif est de pouvoir ainsi donner la possibilité à chaque collaborateur·trice de choisir son environnement d’édition. Il est donc possible d’éditer :
- soit directement sur la plateforme Overleaf en demandant un accès au document ;
- soit dans l’éditeur GitLab ;
- soit sur un ordinateur local en récupérant le fichier à partir de GitLab en utilisant le protocole Git.
La figure [2.7] illustre la procédure de synchronisation entre les deux plateformes.
Conclusion
Ce chapitre constitue un guide méthodologique pour la mise en place de bonnes pratiques documentaires collaboratives au sein du projet. Ce guide ne prétend pas être exhaustif ni même être représentatif des meilleures méthodes à mettre en place dans un projet comme celui-ci. Il propose néanmoins un environnement de travail qui se veut efficace grâce à l’utilisation de certains de ses services (GitLab, ShareDocs, KanBoard) et d’autres interfaces permettant de s’approprier des formats pour la rédaction des documents (markdown, LaTeX). Ce guide est évolutif et d’autres versions seront régulièrement publiées.
(Cycle de vie des données, inspiré de DoRANum 2021): Images/cycle_données.JPG “fig:” {#fig:cycle1 } [1]: #table:outils {reference-type=“ref” reference=“table:outils”} [Git]: https://www.wikidata.org/entity/Q186055 [code informatique]: http://data.loterre.fr/ark:/67375/TSO-MBZXLNPD-1 [2]: #sec:gitlab {reference-type=“ref” reference=“sec:gitlab”} [2.2]: #fig:kan {reference-type=“ref” reference=“fig:kan”} [Vue Tableau du Kanboard HNSO]: Images/kanboard-HNSO.JPG “fig:” {#fig:kan } [3]: #table:nommage {reference-type=“ref” reference=“table:nommage”} [markdown]: https://www.wikidata.org/entity/Q1193600 [2.3]: #fig:sem {reference-type=“ref” reference=“fig:sem”} [Cycle de vie d’un compte-rendu de séminaire HNSO]: Images/cycle-cr-seminaires.jpg “fig:” {#fig:sem } [2.4]: #fig:rsci {reference-type=“ref” reference=“fig:rsci”} [LaTeX]: https://www.wikidata.org/entity/Q5310 [2.10]: #sec:gestion:tutoriels {reference-type=“ref” reference=“sec:gestion:tutoriels”} [Cycle de vie d’un rapport scientifique HNSO]: Images/cycle-rapports_scientifiques.JPG “fig:” {#fig:rsci } [2.5]: #fig:rinterne {reference-type=“ref” reference=“fig:rinterne”} [2.6]: #fig:retro {reference-type=“ref” reference=“fig:retro”} [Cycle de vie d’un rapport interne HNSO]: Images/cycle-rapports_internes.JPG “fig:” {#fig:rinterne } [Un extrait d’un rapport de synthèse]: Images/retroplanning-hnso.png “fig:” {#fig:retro } [Pandoc]: https://www.wikidata.org/entity/Q2049294 [2.7]: #fig:gitsync {reference-type=“ref” reference=“fig:gitsync”} [Arnaud Mercier]: http://codeur-pro.fr/ [4]: Images/procédure_git_overleaf.JPG “fig:” {#fig:gitsync }
Références
La TGIR Huma-Num propose une instance de GitLab parmi ses services.↩︎
Lien vers le site web : https://git-scm.com/↩︎
Le logiciel ShareDocs fait parti de la grille des services de Huma-Num.↩︎
L’équipe du programme HNSO utilise l’instance de Kanboard fournie par la TGIR Huma-Num.↩︎
Disponible à l’url : https://zenodo.org/↩︎
Disponible à l’url : https://hal.archives-ouvertes.fr/↩︎
Lien vers le site Web du projet LaTeX : https://www.latex-project.org/↩︎
Disponible à l’url : https://fr.overleaf.com/↩︎
Disponible à l’url : https://pandoc.org/↩︎
Disponible à l’url : https://pandoc.org/index.html↩︎
Design inspiré des cours d’Arnaud Mercier sur la plateforme Udemy (Arnaud Mercier est un ingénieur logiciel et professeur d’informatique français)↩︎