Quel wiki choisir pour les Compagnons?

Général Évolution de la Communauté
#5

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
1 « J'aime »
#6

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

1 « J'aime »
#7

Sauf que ce n’est pas un wiki!

Je suis désolé de pinailler, mais un wiki ce n’est pas ça.

1 « J'aime »
#8

Je suis assez d’accord avec @freezed.

Les gestionnaires de doc sont de superbes outils et il y a un sujet ici.

Mais un wiki c’est moin contraignant que ce type d’outils.
J’aimerai beaucoup favoriser la participation en limitant au max la friction technique.

J’ai apporté des précisions sur mes idées dans le premier post.

2 « J'aime »
#9

MkDocs ressemble a OneNote un peu non ?

#10

Le OneNote de Microsoft???

#11

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 :slight_smile:

3 « J'aime »
#12

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

1 « J'aime »
#13

Bonjour,

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.

Est-ce que cela à évolué depuis ?

#14

Il y a bien la gestion des droits utilisateurs et l’historique des modifications

1 « J'aime »
#15

Merci @cutty853, je vais essayer à nouveau car j’avais bien aimer l’ergonomie lors de mon précédent essais mais la v2 n’était pas encore sortie.

#16

Salut ici,

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.

2 « J'aime »
#17

Dokuwiki c’est quand même ultra moche non ?

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.

A moin qu’il y ait des thèmes plus élégant ?

#18

Bof, moi je ne trouve ça ni laid, ni beau. J’aime assez bien les thèmes “bootstrap” : https://www.dokuwiki.org/fr:template?plugintag=bootstrap#extension__table

Bon il est vrai que des choses comme Bookstack font un peu plus plaisir aux yeux :slight_smile:

Toutefois l’exemple de wiki “hybride” dokuwiki / markdown / git peut aussi s’imaginer avec un autre moteur de wiki supportant le markdown.

2 « J'aime »
#19

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 :laughing:).

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.

J’avais lancé une discussion dans ce sujet

2 « J'aime »
#20

Bonjour,

Je pensais que mon premier message de la discution était explicite ?
Pour faire court : un wiki utilisable par des non tech.

Donc exit toutes les solutions qui demande d’avoir un compte sur une forge git.

Le but est bien de créer de la documentation en collaboration et de le publier sans modération.

#21

Je pensais que mon premier message de la discution était explicite ? Pour faire court : un wiki utilisable par des non tech.

Sans vouloir trop argumenter, ça, c’est déjà la solution. Quel est l’objectif du contenu sur le Wiki ?

1 « J'aime »
#22

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.

La solution Wiki avait été choisi suite à une consultation de la communauté.

1 « J'aime »
#23

Dans l’épisode VLOG Live du 2022-05-06:

On apprends qu’il y a un wiki en préparation…

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).

#24

En effet on a choisi un Wiki suite à ce sondage.

Il ne faut pas être surpris cela à déjà été débattu dans ce même sujet.

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.