Hello,
Perso j’ai mis en place du WikiJS, qui me parait vraiment pas mal. Pourquoi ?:
On peux mettre de l’authentification externe
Tu as de la gestion de groupe (tu peux faire du ABAC avec des tags sur les pages)
l’ergonomie semble plus simple que BookStack
On peux créer des pages en markdown, en WYSIWYG ou en HTML.
Il est automatisable via une API GraphQL
On peut syncrhoniser les fichiers sur un git (dans les deux sens : pull et push) ou sur un bucket s3 (pour des backups)
Les choses que je n’aime pas sur WikiJS
une fois l’éditeur d’une page choisi, impossible de le changer
la configuration de l’outil n’est pas “automatisable”, il n’existe pas de fichier de config pouvant contenir la config ldap, la config des groupes etc…, tout se fait via l’interface et est stocké dans la bdd
J’aime bien la doc Ansible, elle est faite avec Sphynx. Il y a un bouton “Edit on github”, on clique et ça ouvre le source sphynx et ça gére la pull request directement. Peut être existe-t-il quelque chose du genre avec gitlab ?
Pour ceux qui veulent voir, ça se passe ici : https://docs.ansible.com/ansible/latest/index.html
Je proposais juste une solution pas si éloignée du wiki qui je trouve à un super rendu pour un coût technique accessible à une personne dégourdie.
Question wiki, pour ma part je reste fidèle au bon vieux dokuwiki, il a l’avantage de ne pas utiliser de base de donnée et d’être bourré de plug-in.
Mais celui que tu propose semble très bien aussi pas d’avis particulier sur les autres moteurs vu que doku me convient parfaitement depuis plus de 10 ans
Le besoin étant de d’abord servir des utilisateurs “non initiés”, je pense vraiment que WikiJS est une excellente solution tout en ayant un certain potentiel d’automatisation / génération automatique de document via des synchronisation avec git.
Je l’ai déployé sur du kubernetes avec le chart Helm officiel (il est pas ouf, mais a le mérite d’exister) et des backups Velero quotidiennes (qui envoit tout ça sur du S3). C’est très pratique et rapide à mettre en place. A la différence de Bookstack il me semble qu’il n’y a pas d’instance de démo par contre.
Pour moi les deux solutions à évaluer c’est bookstack ou wikijs
On avais essayé WikiJS il y a 2 ans pour le mettre en place pour un client mais on l’avais ecarté à l’époque car il ne gerrai pas l’historique des modifications ou les droits utilisateurs.
Pour avoir une interface utilisable par n’importe qui, en effet je trouve dokuwiki bien fait.
Avantage de dokuwiki, il écrit une forme de markdown, gère l’historique et dispose d’un bon éditeur wysiwyg.
Je ne sais pas ce que rendrait l’usage de dokuwiki avec git ? Cela permettrait de conserver l’éditeur dans l’interface web, et permettrait à ceux qui le souhaitent de rédiger en markdown localement, avant de pousser leurs changements.
Enfin je veux dire on est très loin en terme d’ergonomie de WikiJS ou Bookstack.
On est vraiment dans un wiki à l’ancienne.
Perso ce genre de wiki je les fuis.
Mon humble avis: commencer par les bonnes questions: quel est le but ? Et reposez-vous la même question plusieurs fois (je commence toujours par ça avec mes clients ).
Vous êtes déjà arrivé à la solution du Wiki, mais quel est l’objectif ?
Personnellement, et avec tous mes clients, que ce soit pour de la doc technique, ou des bases de connaissances, je n’utilise plus que markdown + mkdocs sur GitHub ou GitLab.
Mes objectifs sont les suivants:
Créer une base documentaire (ça, c’est évident)
Pouvoir gérer le cycle de vie de la documentation de la même façon que tout le reste (le code, l’infra, …) avec une ouverture pour la contribution, mais une revue stricte sur le contenu avec discussion possible (Pull / Merge Requests)
S’assurer que la doc est toujours “fraîche” (pas d’hyperliens qui expirent, pas de fautes d’orthographe ou de syntaxe, discipline sur les acronymes (DevOps et pas devops ou DevOPS ou …). Et donc: avoir des tests automatiques sur la doc
Maintenir les liens hypertextes externes, même si le contenu bouge
DRY - Don’t Repeat Yourself: utiliser des macros/includes pour du contenu qui doit être dupliqué (et donc factorisable)
Montrer l’exemple. La doc a justement l’avantage d’être un exemple concret d’implémentation de chaîne CI et CD simple, de pouvoir mettre les mains dedans - même si on est pas développeur Java certifié (!), et de montrer l’exemple.
Partager des connaissances, les organiser et les éditer en collaboration pour que tous le monde puissent participer, et pas que les techs, c’est le pilier “Share” du DevOps.
Je suis surpris ce choix d’outil, parce que pour moi, ce qui marche le mieux depuis longtemps c’est les approches documentation-as-code avec la création d’un site statique (jekyll, hugo, docusaurus… et autres – perso en tant que dev java j’aime JBake).
Autant je suis d’accord pour de la documentation pour un projet particulier avec une équipe restreinte.
Par contre pour créer de la documentation générique par tous le monde, y compris des non tech, un Wiki est plus simple et plus accessible.
Je ne veux pas passer mon temps à valider les MR, je préfère faire de la modération à posteriori.
Selon moi la plus value d’un outil de documentation statique est limité dans un cadre communautaire.
En plus il faudra que l’outil soi connu de tout le monde, alors que pour un Wiki on peu faire du WYSIWYG ou du MD.
).