Structurer et standardiser la documentation partagée SNDS

documentation
snds
(Olivier de Fresnoye) #1

Depuis le lancement de la documentation ouverte et partagée en ligne, nous rencontrons des acteurs qui proposent des éléments à partager avec pour chaque éléments une présentation et une structure spécifique différente. Nous réalisons que chacun de ces éléments est à la fois utile et pertinent mais qu’aucun n’est standardisé ou ne s’inscrit dans une dynamique commune (chacun ayant fait ses propres éléments de documentation en fonction de ses propres besoins).

Nous nous demandons alors, comment nous pourrions structurer tous ces éléments pour optimiser le partage de connaissance et in fine, générer des contributions cohérentes les unes avec les autres.

Que pensez-vous d’identifier des éléments communs de standardisation et ainsi créer des guidelines qui nous permettrons alors d’accompagner chaque contributeur dans l’intégration de ses éléments dans la documentation partagée ?

(Pierre-Alain Jachiet - DREES) #2

Excellente question ! :slight_smile:

Dans un premier temps, je crois que le plus important est d’avoir des contributions de la part d’un maximum d’acteurs. C’est essentiel pour entraîner d’autres contributions, par le même acteur ou d’autres qui suivront le mouvement.

La première contribution de chaque acteur sera difficile, il nous faut donc les faciliter tant que possible.

En ce sens, la contribution la plus simple est de partager des documents déjà existants. On peut simplifier le processus en gérant nous même leur publication et leur présentation.

Pour cette raison, je crois que la standardisation doit être faîte a posteriori. Autrement cela créé une barrière pour les contributions.

Présentation des documents
Nous avons besoin d’informations concernant chaque document.

Je tente une liste, à compléter collectivement :

  • une phrase de description
  • le producteur
  • le format
  • ce qui va intéresser un utilisateur
  • ce qui le rapproche et ce qui le distingue des documents existants
  • comment le document est utilisé en interne de l’organisation qui le publie
  • comment le document a été créé
  • le document est-il maintenu et sera t-il mis à jour (si oui à quelle fréquence ?)

Pour collecter ces informations, le plus simple me paraît de les demander directement à chaque contributeur, lors du partage ou après si oubli.

Nous pouvons présenter ces informations dans la page ressources. Nous réorganiserons et découperons cette page ultérieurement si besoin.

Discussion autour des documents
Même bien présentés, les utilisateurs manqueront certainement d’informations concernant les documents.

Je propose de créer un sujet de discussion pour chaque nouveau document dans la catégorie Documentation-SNDS. Cela permet a minima d’informer la communauté des nouveautés.

Standardisation des documents
Les documents bruts contiennent de précieuses informations. Mais il est compliqué de télécharger et comprendre le fonctionnement de chacun d’entre eux. Je partage donc le besoin de standardiser leur contenu, sous la forme de réutilisations du contenu.

Pour les documents textuels ou image, nous pourrons créer des pages textes au format markdown. Cela facilitera la lecture sur le site de documentation, et les modifications par les lecteurs.
C’est par exemple ce qui a été fait pour le guide d’accès à la documentation du SNIIRAM.

Pour les documents qui décrivent le schéma du SNDS, nous proposons d’intégrer progressivement les informations qu’ils contiennent dans le schéma formel. Ce schéma peut ensuite être rendu dans divers formats. Il est déjà rendu dans le dictionnaire interactif, et la partie tables dédiée de la documentation.
Nous allons nous focaliser prochainement sur ce point.

Pour les codes sources, c’est un sujet légèrement différent qu’il faudra traiter au cas par cas.
Nous avons envisagé d’intégrer quelques requêtes types dans la documentation textuelle.
Pour le reste, il me semble que le plus standard serait d’utiliser des dépôts de code par projet, sous le chapeau de l’organisation INDS ou dans des dépôts spécifiques de chaque organisation.