Commit 21860fda authored by Pierre-Alain Jachiet's avatar Pierre-Alain Jachiet

Relecture et complément sur le guide de contribution

parent b9fef5c8
Pipeline #58219734 passed with stage
in 0 seconds
......@@ -6,7 +6,7 @@ Ce travail est en phase de prototypage. Il est visible à l'adresse [documentati
## Contributeurs
Cette documentation est maintenue par l'INDS, avec l'aide de la DREES.
Cette documentation est maintenue par l'INDS et le Lab santé à la DREES ([contact](mailto:[email protected])).
Elle résulte d'une mise en commun de documents et travaux par plusieurs organisations :
- la Caisse nationale d'assurance maladie - [Cnam](https://www.ameli.fr/)
......
......@@ -3,44 +3,68 @@
Bienvenue sur le guide de contribution à la documentation collaborative !
Nous présentons d'abord le types de contributions que vous pouvez apporter, puis comment procéder.
Cette page présente les grands types de contributions que vous pouvez apporter, et comment procéder.
Des explications pratiques sont disponibles dans les pages suivantes.
## Types de contributions
## Quelles contributions ?
### Partage de documents existants
De nombreux organismes ont documenté le SNDS pour des besoins internes. Ce travail n'est pas accessibles à la communauté plus large des utilisateurs du SNDS. Une première contribution de grande valeur consiste donc à partager publiquement ces documents existants.
De nombreux organismes ont documenté le SNDS pour des besoins internes.
Ce travail n'est souvent pas accessibles à la communauté plus large des utilisateurs du SNDS.
Une première contribution de grande valeur consiste à partager publiquement des documents existants.
Vous pouvez publier des documents sur le site internet de votre organisation. Nous les référencerons via un lien hypertexte dans la section des [ressources externes](ressources#autres-ressources-disponibles-en-ligne).
**Où publier ces documents ?**
Vous pouvez également publier des documents sur ce projet GitLab. Nous ajouterons un lien de téléchargement dans la section des [documents partagés via ce projet](ressources#documents-partages-sur-cette-documentation).
- sur le site internet de votre organisation.
Nous les référencerons via un lien hypertexte dans la section des
[ressources externes](ressources#autres-ressources-disponibles-en-ligne).
- sur ce site internet.
Nous ajouterons alors un lien de téléchargement dans la section des
[documents partagés via ce projet](ressources#documents-partages-sur-cette-documentation).
::: tip Note
Une **licence MPL-2.0** est appliquée sur tous les contenus de ce projet : documents, textes, images, etc.
Le nom de l'organisation sera indiqué dans la description du document, et dans le nom du fichier.
Une **licence MPL-2.0** est appliquée sur tous les fichiers partagés via ce site.
Cette licence autorise une libre réutilisation des contenus. Elle impose cependant que toute nouvelle version d'un contenu doit citer la source, et doit être publiée sous la même licence afin de garantir les mêmes droits (propriété [copyleft](https://fr.wikipedia.org/wiki/Copyleft)).
Cette licence [copyleft](https://fr.wikipedia.org/wiki/Copyleft)
autorise une libre réutilisation du fichier ainsi partagé.
Elle impose à toute version dérivée de citer la source d'origine,
et d'être publiée sous la même licence afin de garantir les mêmes droits.
:::
### Création de nouvelles pages de documentation collaborative
### Amélioration des pages de documentation collaborative
Les contributions visant à corriger des erreurs ou à compléter des pages existantes sont très précieuses.
Toute amélioration, même d'apparence mineure comme la correction de fautes d'orthographe, améliorera pour tous la qualité du contenu.
Les documentations existantes sont éclatées dans de multiples formats : pdf, word, excel, powerpoint, etc. Ces formats rendent difficiles la navigation, la mise à jour et la collaboration. La documentation collaborative est rédigée en texte brut, sur lequel il est facile de collaborer via GitLab.
### Création de nouvelles pages du site internet
Une excellente contribution consiste donc à créer de nouvelles pages de documentation textuelles, par exemple à partir du contenu de documents déjà partagés. Nous organiserons progressivement les pages ainsi crées selon des thématiques cohérentes.
La documentation du SNDS est éclatée dans de multiples fichiers, sous des formats hétérogènes : pdf, word, excel, powerpoint, etc.
Cette disparité complexifie l'exploration des informations,
et rend surtout impossible une collaboration large sur l'amélioration du contenu.
### Amélioration des pages de documentation collaborative
Ce site internet est rédigé en texte brut.
Une excellente contribution consiste à créer de nouvelles pages de documentation,
à partir de vos connaissances ou à partir du contenu de fichiers déjà partagés par ailleurs.
Nous organiserons progressivement les pages ainsi crées selon des thématiques cohérentes.
Les contributions visant à corriger des erreurs ou à compléter des contenus existants sont très précieuses. Toute amélioration, même d'apparence mineure comme la correction de fautes d'orthographe, améliorera pour tous la qualité du contenu.
## Comment contribuer ?
Cette section présente les principaux canaux de contribution.
## Canaux de contributions
### Email
Pour contribuer à la documentation, le plus simple est d'écrire un email aux mainteneurs du projets :
Le plus simple est d'écrire un email aux mainteneurs du projets :
- Lab santé - DREES <<[email protected]>>
- Olivier de Fresnoye - INDS <<[email protected]>>
Nous nous chargerons alors d'intégrer votre contribution.
### Issues
En créant un compte sur gitlab.com, vous pourrez utiliser le système de tickets appelés **issues**, dans cet
......@@ -54,9 +78,9 @@ Chaque issue est l'occasion d'une discussion ouverte pour résoudre le problème
GitLab permet à chacun de proposer des modifications via des **merge-request**, listées dans cet
[onglet](https://gitlab.com/healthdatahub/documentation-snds/merge_requests).
Une formation est préférable pour manipuler facilement `git` et `GitLab`.
Une formation est préférable pour manipuler facilement `git`, `GitLab` et les `merge-request`.
Les mainteneurs du projet organisent de telles formations (gratuites). N'hésitez pas à nous solliciter !
- Pour les autodidactes, nous proposons une [introdution à GitLab](introduction_gitlab.md).
- Pour les développeurs, voici un mémo pour [travailler en local](developpement_local.md).
- Pour les autodidactes, la page suivante propose une [introdution à GitLab](introduction_gitlab.md).
- Pour les développeurs, voici un mémo pour [éditer le site en local](developpement_local.md).
# Développement local
<!-- SPDX-License-Identifier: MPL-2.0 -->
Page plutôt adressée aux développeurs.
Cette page est adressée aux personnes maîtrisant un usage basique de la ligne de commande `git`,
ou utilisant une interface graphique telle que [GitHub Desktop](https://desktop.github.com/) (qui fonctionne pour GitLab).
Les mainteneurs du projet peuvent organiser une formation à ce sujet (contactez nous !).
Nous recommandons également ce [cours en ligne](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github),
dans lequel les mots GitHub et GitLab sont interchangeables.
## Pourquoi ?
GitLab permet d'éditer la documentation depuis un navigateur web.
Cependant `git` est un système de gestion de version **distribué**. Vous pouvez donc - et c'est plus agréable ! - éditer la documentation depuis votre poste de travail avec votre éditeur de texte favori.
Nous avons précédemment décrit comment éditer la documentation depuis l'interface web de GitLab.
Il est cependant plus agréable de travailler en local sur une copie des fichiers avec votre éditeur de texte favori.
Il vous faudra pour cela apprendre l'usage basique de `git`. Les mainteneurs du projet peuvent organiser une formation à ce sujet (contactez nous !). Nous recommandons également ce [cours en ligne](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github), dans lequel les mots GitHub et GitLab sont interchangeables.
`git` est en effet un système de gestion de version **distribué**,
qui permet de créer des branches et des commits sur votre poste de travail,
puis de les partager via une merge-request sur GitLab.
## Visualiser le site en local
Les développeurs peuvent lancer une version locale du site internet avec les commandes suivantes
Les commandes suivantes permettent de lancer une version locale du site internet :
- `yarn install` : installer les modules npm
- `yarn docs:dev` : démarrer le serveur de développement
- Votre navigateur reproduira alors en temps réel vos modifications sur le texte
- Votre navigateur reproduira alors en temps réel vos modifications sur le texte,
à l'adresse [http://localhost:8080](http://localhost:8080)
::: warning Note
Ces commandes devraient fonctionner sur Linux et Mac.
Il faut peut-être les modifier sur Windows
:::
## Organisation du contenu
......@@ -26,3 +39,4 @@ Voici les principaux dossier avec du contenu à éditer
- `docs/.vuepress/public/assets` : ressources fichiers ou images
- `docs/.vuepress/config.js` : configuration du site, notamment des barres de navigation
Se référer à la page suivante pour l'[ajout de nouveaux fichiers](nouveau_fichier.md).
\ No newline at end of file
......@@ -15,7 +15,7 @@ Nous présentons ici une introduction à GitLab pour les autodidactes.
La mise en forme du texte brut est indiquée avec des balises **Markdown**.
Ce texte est alors automatiquement mis sous la forme d'un site internet statique avec VuePress.
Se référer au [tutoriel Markdown](tutoriel_markdown.md) pour plus d'informations.
Se référer au [tutoriel Markdown](tutoriel_markdown.md) pour plus de détails.
## Concepts clés de git et GitLab
......@@ -33,14 +33,17 @@ Les branches de travail sont nommées selon l'objet des modifications apportées
- `merge-request` : Les merge-request (MR) permettent d'intégrer une branche de travail dans la branche principale.
Les modifications seront discutées et validées avant d'être publiées.
Pour cela, les relecteurs commenteront la MR dans son ensemble dans l'onglet *Discussion*, ou ligne par ligne dans l'onglet *Changes*.
Les modifications proposée dans la branche de travail sont discutées et validées avant d'être publiées.
Pour cela, les relecteurs commentent la MR dans l'onglet *Discussion*, ou font des remarques ligne par ligne dans l'onglet *Changes*.
Par défaut, on considère que seul l'auteur initial d'une branche enregistre de nouveaux commits dessus. Si un relecteur souhaite ajouter des commits plutôt que des commentaires, il en demande d'abord le droit à l'auteur afin d'éviter des conflits d'édition.
Par défaut, seul l'auteur initial d'une branche en modifie le contenu, afin d'éviter des conflits d'édition.
Si un relecteur souhaite ajouter des modifications (=commits) sur une branche, il en fait d'abord la demande.
Lors de l'intégration d'une MR à la branche master, d'éventuels conflits d'éditions sont gérés par les mainteneurs. Pour limiter ces conflits, le principe est d'éviter la divergence des branches de travail, en les intégrant rapidement à la branche master. On découpera donc plutôt sur les contributions en petit morceaux cohérents, rapides à valider et intégrer.
Lors de l'intégration d'une MR à la branche master, d'éventuels conflits d'éditions sont gérés par les mainteneurs.
Pour limiter ces conflits, il faut limiter la divergence des branches de travail par rapport à la branche master.
On découpera donc les contributions en petit morceaux cohérents, rapides à valider et intégrer.
## Édition avec gitlab.com
## Édition en ligne sur gitlab.com
La solution la plus simple pour éditer la documentation est d'utiliser le site web gitlab.com.
......@@ -56,7 +59,7 @@ Ce guide se base sur la version anglaise de l'interface, plus courante.
**1- Ouvrir le fichier en édition**
En bas de chaque page de la documentation se trouve un lien, vous invitant à éditer le fichier sur gitlab.
En bas de chaque page de la documentation se trouve un lien, vous invitant à éditer le fichier sur GitLab.
<p style="text-align:center;">
<img src="/assets/img/tutoriel_gitlab/editer_sur_gitlab.png" alt="Éditer sur GitLab" width="200"/>
......@@ -97,12 +100,12 @@ Une page s'ouvre alors pour configurer cette merge-request.
**4- Ajouter des commits sur une branche existante**
Il est possible d'ajouter des commits sur une branche existante. Il apparaîtront alors dans la merge request associée à la branche
Il faut pour cela sélectionner la branche correspondante dans la vue fichier.
Il est possible d'ajouter des commits sur une branche de travail existante.
Il faut pour cela sélectionner la branche de travail dans la vue fichier.
<p style="text-align:center;">
<img src="/assets/img/tutoriel_gitlab/switch_branch.png" alt="changer branche" width="400"/>
</p>
On peut alors éditer de nouveaux documents, a priori ceux du dossier [docs/documentation](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/documentation), et enregistrer de nouveaux commits.
On peut alors éditer de nouveaux documents, a priori ceux du dossier [docs/documentation](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/documentation).
Les nouveaux commits apparaîtront alors dans la merge request associée à cette branche.
# Ajout de nouveaux fichiers
<!-- SPDX-License-Identifier: MPL-2.0 -->
## Nouvelle page de documentation textuelle
L'ajout de nouveaux fichiers demande un peu d'attention. Ne pas hésiter à demander de l'aide !
Les fichiers de documentation textuels sont stockés dans le dossier [docs/contribuer](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/contribuer).
## Nouvelle page du site
Pour créer une nouvelle page de documentation, copier le contenu du modèle présent dans le fichier `modele_markdown.md`.
Les page du site internet sont des fichiers textuels, stockés dans le dossier [docs/documentation](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/documentation).
Pour créer une nouvelle page de documentation, copier le contenu du modèle présent dans le fichier [modele_markdown.md](https://gitlab.com/healthdatahub/documentation-snds/raw/master/docs/contribuer/modele_markdown.md).
Si vous partez d'une page vierge, pensez à ajouter une ligne contenant l'identifiant de licence MPL-2.0 après le titre.
```
<!-- SPDX-License-Identifier: MPL-2.0 -->
```
Pour que votre nouvelle page apparaisse dans le menu de navigation,
il faut l'ajouter dans la variable `sidebar` du fichier de configuration
[docs/.vuepress/config.js](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/.vuepress/config.js).
Pour faire apparaître la nouvelle page dans le menu de navigation du site internet,
il faut ajouter un lien dans la variable `sidebar` du fichier de configuration
[docs/.vuepress/config.js](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/.vuepress/config.js)
(`.vuepress` est un dossier caché).
## Nouveau fichier non textuel
## Nouveau fichier à télécharger
Des fichiers dans un format non textuel peuvent être partagés dans la documentation collaborative.
Des documents de tout format peuvent être partagés dans la documentation collaborative.
Ils seront mis à disposition via un lien de téléchargement.
::: tip Note
Préférer tant que possible des pages de documentation textuelles.
Elle permettent de collaborer efficacement via GitLab pour les améliorer.
De plus, elles sont directement lisible dans le navigateur, sans téléchargement qui est un frein à la consultation.
:::
Pour ajoutez un nouveau fichier, merci de bien vouloir :
- Vérifier que vous avez les droits pour le publier
- Ajouter l'identifiant de licence `MLP-2.0` _dans_ le document, au début
......@@ -36,7 +33,8 @@ Pour ajoutez un nouveau fichier, merci de bien vouloir :
- `nom-du-fichier` : sans espace, car les liens devront sinon utiliser `%20`
- `extension` : par exemple `.csv`, `.pdf`, `.odp`. Préférer des formats interopérables ouverts.
- L'ajouter dans le dossier _caché_ [docs/.vuepress/public/assets/src](https://gitlab.com/healthdatahub/documentation-snds/tree/master/docs/.vuepress/public/assets/src).
- Ajouter un lien dans la page `docs/documentation/ressources.md`, en mentionnant la licence MPL-2.0
- Ajouter un lien dans la page `docs/documentation/ressources.md`,
en mentionnant le nom de l'organisation et la licence MPL-2.0
## Nouvelle image
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment