Utilisation des Wiki pour les travaux pratiques

[Syseria]

Bonjour, en cherchant un peu j'ai découvert la fonctionnalité Wiki de github.

Comme stipulé dans l'article les concernant, cela semble correspondre parfaitement à ce que nous sommes sensé faire (et utiliser) pour la rédaction de documentation longue, voir complexe, afin de ne pas surcharger le README.

Si nous décidons d'utiliser cette fonctionnalité pour la rédaction du protocole, où devons-nous stipuler que le document se trouve dans l'onglet Wiki ? Dans le README ou dans la discussion que nous avons ouverte il y a quelque semaine (#496) ?
Il n'y a (à ma connaissance et surtout observation) pas de visual cue démontrant qu'un Wiki est crée et possède des pages.

[ludelafo]

Bonjour Nicolas,

Merci pour votre message.

Je pense que le plus simple pour votre cas est de simplement le stipuler dans le README de votre projet avec une note du style "La documentation de ce projet est disponible dans le wiki de celui-ci" de telle manière à ce que toute personne qui tombe sur votre projet en soit informé.

Il existe un visual hint lorsqu'un Wiki est présent sur un projet dont vous pouvez voir un exemple sur ce repo : https://github.com/prettier/prettier. L'onglet Wiki s'affiche dans le bandeau principal du projet mais cela ne permet pas de savoir s'il y a un contenu ou non.

À titre personnel, je ne suis pas fan des Wikis. Il s'agit une opinion complètement subjective et vous êtes tout à fait libre d'utiliser ces fonctionnalités de GitHub (et bravo d'ailleurs d'avoir fouillé dans les options pour la trouver) mais voici les raisons pour lesquelles je n'aime pas trop travailler avec les Wikis sur GitHub/GitLab :

• Je trouve que ça rajoute de la complexité car cela dissémine l'information entre le code source du projet dont j'ai les accès localement (en ayant cloné mon repo localement) et la documentation du projet qui, elle, est disponible ailleurs, dans un wiki en ligne. Il est tout à fait possible de cloner le Wiki comme n'importe quel repo Git mais je dois ensuite gérer deux repos localement et les garder synchronisés lors de mise à jour d'un côté ou de l'autre.
• En ayant ces deux notions séparées, je trouve que cela complique le maintien et la mise à jour "atomique" d'un projet et de sa documentation associée : si je mets à jour du code dans mon projet, je ne peux pas le faire dans une même PR "d'un seul coup" et je ne dois pas oublier de mettre à jour la documentation associée dans le Wiki. C'est d'ailleurs un souci que j'ai avec le cours de DAI actuellement car une mise à jour de la théorie me demande souvent de mettre à jour les exemples et les solutions, tous séparés dans des repos différents, ce qui implique une friction non négligeable que j'aimerais éviter l'année prochaine en fusionnant les trois repos ensembles.
• Je trouve un Wiki plus difficile pour la collaboration car il n'y a pas, à ma connaissance, la possibilité de passer par des issues/PRs/reviews et discussions sur les changements apportés/souhaités sur un Wiki. Tout est beaucoup plus libre et j'ai le ressenti que sur un projet d'envergure, les soucis peuvent arriver plus facilement à cause de ça.
• Selon ce que je veux faire ou représenter (diagrammes, exemples, vidéos, GIFs, etc.), je suis limité par les fonctionnalités du Wiki qui ne me laissent pas assez de liberté dans ce que je veux faire (ironique par rapport à ma dernière remarque).
• J'ai souvent trouvé les Wikis peu agréables à naviguer et l'information peu accessible/facile à trouver en comparaison à pouvoir ouvrir mon projet, faire une recherche ou utiliser le site web dédié pour la documentation. Peut-être que cela s'apparente plus à des "skill issues" mais je me perds trop fréquemment dans les peu de Wikis sur lesquels je tombe.

Ce sont les raisons principales (à tort ou à raison) pour lesquelles je préfère travailler directement dans le repo principal de mon projet (et que j'ai désactivé la fonctionnalité des Wikis dans tous les repos pour éviter une confusion). Cela ne me dérange pas d'avoir le code et sa documentation associée au même endroit (en moyennant de mettre la documentation dans son propre dossier docs par exemple) pour éviter ces soucis.

Après, la difficulté rencontrée, c'est l'organisation de l'information, qu'elle soit dans un Wiki ou dans un repo commun. Pour cela, j'ai trouvé les ressources suivantes très intéressantes et très utiles que je ne peux que vous conseiller d'explorer. Ce sont en grande partie ces ressources que j'ai utilisées pour construire le cours de DAI et dont j'en parle dans un "meta-chapitre" "Material for the teaching staff" disponible dans le repo principal du cours ici : https://github.com/heig-vd-dai-course/heig-vd-dai-course/tree/main/99-material-for-the-teaching-staff :

• Diátaxis - How to structure technical documentation
• Johnny.Decimal - How to organize files

Et d'autres ressources qui m'ont été partagées dans la même thématique :

• https://redhat-documentation.github.io/modular-docs/
• https://gitlab.com/tgdp

Si je dois gérer une forme de documentation "avancée", je priorise de le faire directement au niveau du projet, au même endroit que le code, en utilisant Diátaxis et Johnny.Decimal, à l'aide d'un générateur de site statique tel que Material for MkDocs (https://squidfunk.github.io/mkdocs-material/), comme sur le projet suivant sur lequel j'ai bossé mais qui est un peu en suspens ces temps : https://docs.beescreens.ch/.

Pour le cours de DAI, mon souhait était de rester le plus simple possible, avec le moins de barrières/points d'entrées possibles et j'ai opté pour rester le maximum dans GitHub avec du vanilla Markdown et une organisation basique de l'information.

Je me suis un peu égaré concernant votre question, mais dans le contexte du cours de DAI, ce qui nous importe est d'avoir accès à cette information sous une forme ou une autre. Si vous souhaitez tout mettre dans le README, avoir deux fichiers séparés README.md et APPLICATION_PROTOCOL.md, mettre en place ou Wiki ou autre, c'est OK pour nous tant que l'on peut retrouver facilement le tout.

J'espère avoir répondu à votre question et je reste dispo si besoin !
Bon weekend,
Ludovic