J’ai récemment fait une présentation pendant “All Day DevOps” au côté de Laurent Gil sur CI et CD pour la documentation.
Le replay est ici et les diapos ici (sur GitHub, avec des GitHub actions pour illustrer le propos).
Et vous, vous pratiquez ? Parceque nous, on est fans 
Bonjour @ojacques
Je suis moi aussi en plein dans cette démarche d’industrialisation de la documentation.
L’idée étant d’avoir à un seul endroit toute la documentation au format markdown et qu’elle soit facilement maintenable dans le temps.
Pour ma part j’utilise le générateur de site statique vuepress et je m’intéresse aussi au thème mrhope qui semble ajouter plein de features sympa comme la gestion de slides, la génération de workflow, … le tout en markdown.
Un avis sur ces technos ?
Bonne journée,
Benjamin
J’utilise principalement mkdocs, avec le thème material.
Pour les sites très “fancy”, j’utilise Hugo.
J’aime bien mkdocs parceque:
J’avais entendu parler de Vuepress, mais pas vraiment regardé encore.
J’utilise hugo avec un theme particulier pour gerer une arborescence. Par contre les collègues sont pas convaincus 
(mais on vient de loin, migration cvs git il y a peu)
Bonjour
J’utilise lektor pour générer mon site web à partir de la CI de gitlab. Ca permet d’écrire le site en markdown.
Mais, depuis, j’ai découvert org-mode qui permet de générer du markdown (et plein d’autres formats: reveal.js word, html, gfm). Je n’utilise plus que ce format pour écrire de la doc ou des présentations. Un jour, je convertirai mon site en org-mode…
Je trouve Hugo vraiment top quand il faut faire de gros sites, de type “marketing” où le format est prépondérant. Mais pour la doc technique, je préfère mkdocs pour sa simplicité et les possibilités d’extension qui m’ont toujours permis de répondre aux différentes situations.
Pour ceux qui ont connu Jekyll: j’ai arrêté à cause de sa lourdeur et la difficulté de faire tourner les sites sur les postes de tous (Windows !).
Je suis fan!
J’ai découvert avec GitLab et depuis septembre mon nouvel employeur utilise Confluence, et franchement, c’est la déprim 
J’en parle dans mon Meetup Virtuel d’octobre #autopromo
J’ai testé lektor, pour sa promesse de «mise a jour faisable par un non-tech» (pas de git et wysiwyg), mais je l’ai trouvé plus lourd a mettre en place que pelican, et a forciori mkdocs.
Qu’est ce qui t’as motivé?
As-tu pu mettre du lektor dans des main non-tech?
Qu’est ce qui t’as motivé?
J’ai essayé plusieurs générateurs sans trop comprendre comment faire. lektor est le premier qui m’a permis de sortir quelque chose de correct sans que j’y passe trop de temps,
Cerise sur le gâteau: lektor est disponible sur ma machine Debian avec “apt get”. Les mises à jour sont donc très faciles.
As-tu pu mettre du lektor dans des main non-tech?
Non, je n’ai pas essayé
HTH
Et bien pour ma part : mkdocs et certains outils de générations de doc d’API comme Swagger UI, le tout propulsé par Gitlab Pages.
Par contre, beaucoup de clients demandent d’avoir la doc sur Confluence, je n’aime pas mais pas le choix.
Par contre, beaucoup de clients demandent d’avoir la doc sur Confluence, je n’aime pas mais pas le choix.
J’ai eu ce cas de figure dans un boulot précédent: je devais écrire une doc dans un wiki Confluence 
. Je l’ai écrit en org-mode (c’est le même principe que markdown), puis exporté en fichier libreoffice et importé dans Confluence en tant que document Word. 
Super présentation,
J’ai découvert quelques outils intéressant à ajouter à notre stack comme le linter de lien 404.
On utilise en partie les mêmes outils avec quelques extensions en plus. Avez-vous essayé Mermaid à la place de drawIO et PlanUML. Moi j’en suis bien content et je trouve cela plus simple à prendre en main.
Je suis tombé sur Mermaid après avoir mis en place PlantUML.
J’avais déjà été relativement incompris avec ma volonté d’automatiser le modèle de donnée d’un projet alors je n’ai pas pris le temps de tester Mermaid du coup…
Un compagnon aurait peut-être utilisé ces 2 outils pour en faire un retour?
Concernant la génération de diagrammes, je recommande https://kroki.io/ (développé par un ami, j’ai donné un coup de main pour la CLI) qui supporte quasi tous les formats de diagrammes et permet de facilement les tester, générer, et inclure dans de la doc.
Vous pouvez même passer votre diagramme texte en base64 en paramètre d’URL et kroki vous le générera, vous n’avez besoin de rien en local (voir la page examples).
J’avais fais une tentative avec Mermaid mais la syntaxe devient très vite indigeste. Du coup, je suis passé à Diagrams : https://diagrams.mingrammer.com/.
Mes retours perso sur
Ouais, merci mcorbin pour kroki, je vais tester ça.
Pour les archis, y a diagrams pour faire du diagram as code.
Il existe le pendant en golang (mais moins fourni de mémoire). Je peux retrouver le lien si ça intéresse.
L’intégration Kroki est maintenant disponible dans Gitlab (ça vient d’arriver avec la dernière release): https://docs.gitlab.com/ee/administration/integration/kroki.html
Hello @ojacques,
Merci pour ton partage. J’ai vu dans les slides que tu utilisais markdown-link-check. Je l’utilisais aussi pour vérifier les liens de mon wiki sous gitlab, et comme j’avais quelques modifications à apporter au projet, je l’ai forké, réecrit complétement en typescript et ajouté des fonctionnalités (gestion multi pages, cache, statistique, …). Si vous êtes intéressés par cette version, voici le point de départ : https://www.npmjs.com/package/@boillodmanuel/markdown-link-check (+ le repo github). A votre dispo si vous avez besoins d’info ou de features.
Manuel