Forum

Possible ou pas, que cela soit Markdown, Pandoc et DocBook semble être des formats et des outils de publication documentaire libre. Avec ces outils cela permettrait de porter la doc dans une multitude de formats en gardant la pérennité.

Personnellement, je pense que c'est possible, cela demande juste à être structuré et motivé.

Bonjour,
Je ne connais pas bien pandoc. Je crois que une sorte de couteau suisse de la doc.
Docbook, c'est le format utilisé par notre documentation officielle, à travers la plateforme Calenco.
Markdown peut-être intéressant, c'est de plus en plus largement utilisé. Le souci est qu'il y a des dialectes. Tu le vois pour qu'elle application?

Bonjour,

Pour Mardown, c'est génial pour prendre des notes ou écrire des README, je ne suis pas certain que ce soit le format de choix pour une documentation complète.

Alors, pourquoi cette idée, parce que, d'après ce que j'ai cru comprendre, à partir de markdown on peut porter la doc dans tous les formats, epub, HTML, MediaWiki même écrire un livre (futur projet😁). Et apparemment il est très simple dans toutes les langues.

J'utilise Pandoc pour produire des pages HTML à partir de fichiers Markdown. Avec le template qui va bien, il fait même de très beaux PDF. Je l'utilise aussi, inversement, pour convertir n'importe quoi en fichier texte. Oui, c'est bien une espèce de couteau suisse. Les filtres Lua permettent éventuellement de modifier à son souhait le processus de conversion.

Les dialectes, c'est (à mon avis) parce que les gens veulent dépasser les limites du format et ajouter des possibilités qui n'y sont pas. Mais à ce moment-là autant utiliser un format plus élaboré.

Un ami me disait récemment le plus grand bien d'AsciiDoc, mais je ne l'ai pas encore essayé. Docbook, pareil, on m'en a parlé mais je ne connais pas.

Là vous parlez de quelle documentation ?

Les échanges sur les forums, MLO ou Mageia, avec la documentation sur les wikis ou officielle constituent le cœur de l’aide que nous recherchons.
Écrire de la documentation est fastidieux, et tous les contributeurs le savent. L’objectif est donc de trouver un outil qui permette d’avoir un cœur solide, facilement exportable vers plusieurs formats, sans prise de tête, même si « il y a toujours quelques petits couacs ».
Pour les sites statiques, j’ai trouvé MkDocs. Temps d’installation : environ 3 minutes montre en main. Le multilinguisme peut être géré facilement.
Mais : la gestion de la documentation passe par Git, ce qui peut être un frein pour certaines personnes.

Wiki.js prend également en charge le langage Markdown. Wiki.js nécessite toutefois une base de données pour fonctionner, mais le multilinguisme peut facilement être mis en place et les contributions sont plus accessibles.