J’ouvre ce sujet pour partager des expériences et conseils sur les différentes solutions possibles pour qu’un groupe de personnes rédigent et maintiennent à jour des contenus publiés en accès libre. Ce sujet est complexe car il dépend notamment beaucoup de la taille du groupe, de la fréquence de mises à jour des contenus, si l’on est dans une processus d’écriture/relecture ou de co-écriture, la licence appliquée sur les contenus, des exigences sur la façon de diffuser les contenus.
Dans le cas présent, le sujet se concentre sur un processus de collaboration dont le but est de faciliter la co-écriture ouverte d’une base de connaissances diffusée sur un site internet accessible à tous.
Ce sujet de discussion est de type wiki mis à jour au fur et à mesure des expérimentations et partages relatées dans la discussion. Toute personne active régulièrement sur Koweb Kafé a la possibilité de le mettre librement à jour : ajouts d’informations, correction d’erreurs, …
Exigences sur les solutions à imaginer
- taille du groupe : une équipe resserré d’auteurs ayant la capacité de rédiger et valider les suggestions + ouverture à tout volontaire souhaitant faire des suggestions
- fréquence de mise à jour des contenus : intense au début puis modifications à la marge
- type de processus d’écriture : co-écriture à plusieurs auteurs couplé à des mécanismes de suggestions/relecture/discussions pour validation par un des auteurs
- licence sur les contenus : licence CC-BY-SA 4.0 permettant librement la réutilisation et le remix des contenus tout en reconnaissant les auteurs à leur origine.
- diffusion des contenus : sur un site internet en libre accès où les personnes pourront discuter dessus et rapidement basculer en contributeur pour suggérer des modifications.
La solution doit permettre aussi
- d’automatiser au maximum les allers/retours entre consultation et modification du contenu.
- d’avoir une courbe d’apprentissage faible pour toute personne souhaitant contribuer au contenu
Créer un grille d’analyse des solutions selon les critères pour effectuer un graphique en araignée évaluant chaque solution. Le fichier Google Sheets en cours d’élaboration : Analyse des solutions de documentation collective ouverte - Google Sheets (demandez les accès si vous souhaitez contribuer)
Ce qu’il faut questionner et savoir pour ce type de chantier
Comment accéder / consulter la connaissance ?
Comment on lit, nous sommes tous tombés d’accord pour dire que des pages internet sur un site internet est une base formidable pour lire la documentation. Par contre pour l’écrire, il faut définir les besoins et les contextes.
Quel support pour écrire la connaissance ?
3 grandes familles se distinguent pour écrire la connaissance. Chacune permet en général
- de conserver un historique et ainsi de revenir en arrière si besoin
- ouvrir ou restreindre l’écriture à un groupe de personnes
Les familles d’outils pour écrire
-
Les Pads : ce sont les documents en ligne pour de la co-édition en temps réel. En fonction de l’outil, il est possible de restreindre l’écriture à un groupe de personne. Certains vont permettre de faire des commentaires, de suggérer, de discuter et d’autres non. Il faut alors les associer à d’autres outils.
Les outils : Etherpad, Cryptpad, HedgDoc, Google Docs, OnlyOffice, Collabora, …
-
Les wiki : la collaboration n’est pas en temps réel. En général, l’écriture est publique et la discussion sur ce qui est écrit est généralement difficile. La collaboration repose sur le fait qu’il est plus facile de revenir sur un changement que d’en ajouter un.
Les outils : Mediawiki, YesWiki, Discourse (en mode wiki)
-
Git : c’est plus un espace de stockage de la documentation associé à un flux de travail de proposition, relecture puis intégration. Les outils d’édition sont sommaires et il faut associer Git à un autre outil pour rendre accessible la contribution au passant.
Les outils : Gitlab, GitHub, Gitea, …
Le format d’écriture
Il faut aussi prendre en compte le format d’écriture. Le Markdown est la syntaxe de mise en forme d’un contenu qui est le plus populaire aujourd’hui. L’utiliser permet de rendre la documentation beaucoup plus portable. Par exemple, à partir de d’un même contenu en markdown, il est possible de publier au format PDF, Word, ou HTML (page internet).
Des éditeurs en ligne rendent transparent la syntaxe pour éviter à un-e rédacteur-trice de l’apprendre.
Quel flux de travail pour aller de l’écriture à la publication ?
Rédiger et étoffer cette section
Un premier pilier nécessaire au flux est l’espace de discussions sur ce qui est écrit.
La difficulté de mise en œuvre technique de la solution
Dans les différentes discussions, il apparait clairement que des solutions sont pratiquement clés en main pour des personnes qui savent utiliser un clavier, écran et souris. Par contre certaines nécessitent des connaissances techniques qui vont faciliter la mise en place du flux de travail.
Une documentation s’inscrit dans la durée et il est donc nécessaire de choisir une solution technique que la communauté sera en capacité de maintenir dans la durée.
Solution 1 : rédiger avec Google Docs et diffuser avec une solution dédiée
Google Docs est un outil puissant pour rédiger à plusieurs un document.
- Il se prend facilement en main et il n’est pas nécessaire d’avoir un compte Google pour suggérer des modifications.
- L’historique de révisions permet de faire reconnaitre les différentes contributions de chacun.
- Pour suivre ses suggestions, ses commentaires et les réponses des autres, le compte Google est nécessaire pour recevoir des notifications par courriels. Ce mécanisme facilite le réengagement de chaque contributeur dans le processus de collaboration.
Trois outils permettent de transformer un dossier de documents Google Docs en un site internet :
- Kbee : à partir de 15$ par mois mais pour ce que l’on souhaite faire, c’est la solution à 59$ / mois qu’il faudrait prendre afin de dépasser la limite de 30 documents. Ses atouts principaux : personnalisation du site et fonction de recherche.
- Circular, repéré le 8 février par @lolozere. 20€/mois environ jusqu’à 5 collaborateurs et encore en cours de développement.
- You need a wiki : similaire à Kbee avec des fonctionnalités en moins (recherche dans le contenu, personnalisation du rendu, …). Prix bien plus accessible voire gratuit au début (à tester).
- Library est un outil open source développé par le New-York Times. Il doit-être installé chez un hébergeur (coût variable selon l’hébergeur). Un moteur de recherche permet de trouver du contenu sur le site publiant le contenu.
Le choix de la solution peut aussi dépendre de l’exigence que l’on a sur la confidentialité des informations dans les documents. Dans notre cas étant donné que le but est de rendre le contenu public, ce critère n’est pas important. S’il l’était, il faut sans doute privilégier You need a wiki (car les documents ne transitent pas par leur serveur) et Library (car nous avons la main sur toute la chaine du fait que c’est une solution Open Source à déployer soi-même).
Les solutions Kbee et You need a wiki présentent une limite si l’on souhaite intégrer un fil de discussions sur chaque page. Library étant une solution Open Source, un développeur peut effectuer l’intégration d’un outil de discussions comme Commento ou Discourse.
Todo
- : tester Kbee
- : tester You need a wiki
- : tester Library
Solution 2 : utiliser une forge Git comme GitHub/Gitlab avec l’aide d’outils simplificateurs pour néophytes
L’idée est venue en découvrant cet article : Content contribution to the GitLab marketing website via Netlify CMS | GitLab
Git : c’est quoi et pourquoi il permet de collaborer sur du contenu ?
Git est un logiciel de gestion de versions décentralisé. C’est un logiciel libre créé par Linus Torvalds - Wikipedia
Un dépôt Git permet de stocker des fichiers textes et suivre ses évolutions de version en version : qu’est-ce qui a été modifié et par qui. Des plateformes comme Github ou Gitlab utilisent Git pour proposer une plateforme complète de collaboration sur les fichiers : gestion des droits sur les fichiers, proposition de modifications, gestion de demandes d’améliorations (issues), révision à plusieurs de chaque modification avant validation.
Git est utilisé très majoritairement pour collaborer sur des fichiers textes nécessaires au développement de logiciels. L’idée est de l’utiliser pour des fichiers textes de contenus comme des articles ou des pages. Voici une démonstration vidéo de discussions sur des lignes de fichiers textes (ici du code informatique mais imaginez que ce sont des lignes d’un article) : - YouTube
Les principes de la solution imaginée
Le but est donc d’utiliser la puissance de Git et Github pour permettre aux auteurs d’un contenu d’effectuer une relecture fine des modifications souhaitées avec la capacité de discuter. Il faut toutefois simplifier la tâche à ceux qui souhaitent effectuer des suggestions ou corrections comme s’ils étaient sur un outil d’écriture habituel de documents.
Les briques logicielles pour réussir cela sont :
- Decap CMS : c’est un outil d’édition de contenus stockés dans un dépôt Git. Le contenu est rédigé en markdown et bénéficie donc de tout ce que permet Git. Son interface d’édition de contenu est très simple et en le configurant il est possible de mettre en place un processus de relecture avec publication.
- Github ou Gitlab : plateformes collaboratives basée sur Git pour stocker et produire à plusieurs du contenu comme du code source informatique ou des articles.
- Des générateurs de sites comme Jekyll pour générer un site à partir de fichiers markdown (ceux contenus dans Github/Gitlab)
- Des outils de publication automatique sur internet comme Gitlab Pages ou Github Pages
Exemples de mises en œuvre
- Le retour d’expérience de @lolozere sur une mise en oeuvre avec le guide des outils libres pour collaborer
Les limites et avantages de cette solution
Pour s’engager dans cette solution il faut dans l’équipe des personnes compétentes pour mettre en place les outils. Les contributeurs devront se créer un compte sur Github ou Gitlab pour proposer des modifications aux auteurs et s’ils souhaitent discuter de ces modifications alors un apprentissage sera nécessaire pour se familiariser avec l’interface de Github (en anglais). Gitlab a l’avantage d’être disponible en français.
-
→ il est facile pour une communauté plus large de modifier à la marge le contenu puis des responsables relisent et valident -
→ la co-écriture intense au début est complexe avec cette solution sauf si les contributeurs-trices sont formés en amont
L’outil permet de tracer précisément qui a écrit quoi et de se faire une idée des personnes qui contribuent le plus. Il apporte ainsi une reconnaissance aux auteurs principaux (exemple : Contributors to decaporg/decap-cms · GitHub).
Toute la chaine, de la production à la diffusion du contenu, se base sur des outils Open Source. Les coûts de la solution reposeront donc sur son hébergement via un prestataire et sur le temps passé par des techniciens pour la mettre en place et la personnaliser. La rentabilité se mesurant donc plus sur le long terme.
Les autres solutions
Les documentations à la façon wiki
Note interne de @lolozere :
ré-évaluer les outils type wiki pour les intégrer dans une solution déployable
Les wiki en général comme YesWiki ou Mediawiki. Ces outils ne permettent pas de co-écrire et discuter facilement sur des mots ou idées présentent dans le contenu. Il faudrait complexifier le processus de rédaction avec un outil comme Google Docs puis exporter le contenu dans le wiki et réaliser l’opération inverse si un personne modifie directement une page de wiki afin de conserver le document Google à jour.
Le mode wiki du forum Discourse. Discourse a pourtant de beaux atouts :
- Discourse dispose d’un mode wiki pour les sujets.
- Étant orienté discussions, toute personne du forum peut discuter le conteu.
- La fonction « citation » permet de sélectionner un texte du contenu puis de le citer dans un message afin de le commenter.
Cependant dans le cadre d’un contenu en cours d’écriture à plusieurs, la lecture de tous les messages dans le fil de discussion deviendra fastidieuse. Cette solution semble donc à privilégier quand un contenu est stabilisé et le sujet wiki devient le document de référence sur lequel tout le monde se réfère.
Documentation basée sur les pads de HedgeDoc
@pierre.trendel a travaillé sur la publeash pour générer un guide à la volée à partir d’un contenu existant ou pour produire en direct sur un évènement. C’est une démonstration d’un flux de travail où la connaissance s’est écrite dans différents contextes de collaboration et qu’un outil tente de rendre présentable pour en faciliter une consultation organisée. Exemples :
- Une expérimentation menée pour les communs des tiers lieux
- Aller sur Vite + Svelte et saisir Alice’s Adventures in Wonderland - HedgeDoc dans le champ de saisie et cliquez sur Actualiser. Alice au pays des merveilles en ligne
D’autres initiatives et projets allant vers cette voie :
- https://pinkmypad.net : Pink my pad est une application toute simple qui transforme vos pads en une page web statique.
Les solutions en développement
Ce sont les solutions qui sont encore très peu documentées et dont leur construction est encore en cours pour permettre un usage plus large.
- https://gogs.io/ : une alternative en auto-hébergement de Gitlab. Bcp plus simple, et surtout, le source des templates de l’interface est très accessible (c’est en Go, et les templates sont à travailler comme dans le SSG hugo). Du coup, ça ne serait peut-être pas si compliqué de faire une interface ultra-basique repensée pour des utilisateurs non usagers de Git… - Une proposition de @pierre.trendel à discuter ici
à compléter
Les petits outils pratiques qui peuvent aider
Des outils d’annotation comme Glasp ou Hypothesis : ils peuvent par exemple aider pour qu’une ou plusieurs personnes fassent des retours sur le contenu d’une page internet puis le partager aux autres (les rédacteurs par exemple). Ils aident à mieux illustrer des suggestions qui seraient faites dans un outil de discussions (chat, forum, mail).
Glasp
C’est un outil pour annoter annoter et surligner une page internet et le partager.
- Site internet : https://glasp.co/
- Les messages de la discussion sur cet outil : Analyse rapide de @lolozere et précisions de @StereoTraining
L’outil ne permet pas discuter sur les notes de chacun par contre il permet à ceux qui s’inscrivent sur Glasp de partager un lien unique de ses notes, consultable sans compte Glasp, et ainsi suggérer des choses. Un compte Google est nécessaire pour s’inscrire et une personne en charge de modifier le contenu peut avec son compte consulter les notes faites par chacun (personne par personne).
Hypothesis
Effectuer une synthèse de l’analyse faite par @StereoTraining ici
Hypothes.is aide à commenter pour discuter sur ce qui est écrit.
Bibliographie et contributeurs-trices
- Trello ou Kbee pour constituer une base connaissance à partir de Google Docs
- We Built a Collaborative Documentation Site. Deploy Your Own With the Push of a Button. | by The NYT Open Team | NYT Open
- Content contribution to the GitLab marketing website via Netlify CMS | GitLab
Ils ont participé à la discussion et permis d’améliorer l’écriture de cette documentation
Todolist
Si vous souhaitez contribuer à cette expérience, vous pouvez effectuer des actions listées sous forme de case à cocher dans les sections précédentes.
Une étape suivante serait de créer un gabarit duplicable de cette solution et un mooc pour que n’importe qui puisse lancer une documentation collaborative en ligne.
)