Cycle de la documentation du projet Duniter : dans le dépôt git, sur le site web

Oui alors ça c’est un autre point dont il faut qu’on discute mais je trouve perso qu’avoir la doc technique dans un autre dépôt c’est vraiment pas pratique :

Je pense à mettre à jours la doc seulement au moment où je fais le dev, après j’oublie, sauf qu’entre le moment ou je vais un dev et le moment ou il se retrouve dans une version stable il peut se passer plusieurs mois, je ne peux donc pas mettre à jours la doc du site au moment du dev, et donc la doc du site est nécessairement jamais à jours…

Je préférerais que toute la doc technique soit dans le dossier doc du dépôt de Duniter, et que le wiki du site web aille piocher son contenu dans ce dépôt (sur la branche de production). Ainsi, quand une release est poussée en stable, ça mettrait automatiquement à jours la doc du site sans qu’on ait besoin d’y penser, qu’en pensez-vous @Moul @anon88550267 ?

2 J'aimes

C’est pas simple à résoudre comme problématique.

Pour que la documentation passe du dépôt git du code source au dépôt git du site web il faudrait soit faire des copier/coller assez souvent, ou une synchronisation automatique soit utiliser un git subtree, mais je suis pas sûr qu’on puisse intégrer juste le dossier doc.

Il y a plusieurs approches. Le projet Silkaj a toujours sa doc dans le dépôt du code source, mais ManUtopik « souhaite l’externalisez » d’une certaine manière.

C’est top d’avoir la doc et le code synchronisés et faisant un seul et même changement qui met à jour les deux.

L’autre approche et d’avoir les deux dépôts séparés, comme pour le projet YunoHost, et ça a bien fonctionné, car il y avait quelqu’un de dédié à la documentation qui suivait l’évolution technique du projet pour la mettre à jour. C’était moi. Sinon, les développeurs n’avaient pas la patience de le faire, car en tant que développeur tu as trop la tête dans le guidon, et que la doc c’est un peu le dernier des soucis, surtout si ce dernier se trouve dans un autre dépôt. Du coup, dans ce cas, il faut quelqu’un de dédié à la documentation et qui suive les évolutions du projet. Peut-être un problème de manpower.

Je déconseille fortement les git subtree, il y a bien plus simple :

Dans le process de build du site on intègre les .md qui se trouvent dans le dossier doc du dépôt Duniter, on peut formater ces .md comme il faut pour le site :slight_smile:

Et je suis contre la solution d’un documentateur, même si on avait le manpower, ça resterait infiniment plus pratique et plus précis que se soit le dev qui documente au moment ou il fait son dev, en tout cas c’est comme ça que je fonctionne perso, et je ne me vois pas devoir à chaque fois expliquer a un documentateur ce qu’il faudrais documenter, le texte que j’écrirais pour lui expliquer ferait doublon avec la doc, autant écrire la doc directement.

Je ne vois pas ce qu’il y a de compliquer a intégrer les .md du dossier doc dans un script de pré-build du site.

Je ne pense pas qu’il va y avoir besoin de modifier grand chose :slight_smile:

À première vue, je dirais qu’il faudra juste que le script renomme ton fichier

README.md

en :

blockchain-rust.md

pour garder le permalien SEO

duniter.org/fr/contribuer/blockchain-rust/

Après il faudra voir comment tu veux gérer les langues aussi. Est-ce que tu écris tout en français, tout en anglais, ou est-ce que tu écris dans les deux langues :question:

Perso je n’ai pas la compétence pour faire ça. Mais si quelqu’un sait faire et peut allouer du temps pour écrire le script c’est ok pour moi.

Non le README est dédié à être la page d’accuil du dépôt. Ce n’est pas lui qu’il faudrait binder au site mais les différents tutos du genre :

  • doc/architecture.md
  • doc/contribute-french.md
  • doc/docker.md

etc

Je suis justement en train de travailler a la mise à jours de ces fichiers, qui était resté en obsolescence justement car la doc se faisait désormais sur le dépôt du site web.

Dans les 2 langues :slight_smile:

je ne sais pas a quel endroit il faudrait placer chacun des fichiers, ça dépend de l’arborescence du site, mais pour les récupérer, il suffit de cloner la branche stable du dépôt Duniter (de mon coté je m’assure que cette branche stable pointe toujours sur la dernière version stable de Duniter).

Pour ce faire :

git clone https://git.duniter.org/nodes/typescript/duniter -b stable --depth 1
cp duniter/doc/docker.md chemin/de/destination/de/article/docker
cp duniter/doc/architecture chemin/de/destination/de/larticle/sur/larchitcture/de/duniter
...
rm -rf duniter