Salut tout le monde,
Je dois rédiger de la documentation utilisateur en ligne et je voudrais pour cela utiliser un générateur de site statique, pour les côtés facile à déployer, sources "lisibles" et "versionnables".
Précision importante, la documentation ne s'adresse pas à des développeurs mais à des utilisateurs donc j'ai besoin de pouvoir insérer des images, des tableaux et de les mettre en forme, bref de pouvoir faire un peu de mise en page. Et bien que je connaisse un peu de HTML/CSS je ne suis pas moi-même développeur.
J'ai essayé quelques outils connus mais la plupart utilisent du Markdown pour les sources, qui me semble assez pauvre au niveau de la gestion des images/tableaux. J'ai également regardé du côté d'outils permettant d'utiliser AsciiDoc ou reStructuredText (qui m'ont l'air d'avoir des possibilités plus étendues que Markdown en termes de mise en page) mais c'est pas toujours bien pris en charge (cf. mes essais ci-dessous)…
Pour le moment j'ai essayé les outils suivants :
- MkDocs : Markdown seulement mais pas mal pour ce que j'ai testé.
- GitBook : semble parfait au premier abord et gère AsciiDoc. Pour ce dernier la doc de Gitbook renvoie vers celle d'AsciiDoctor mais en pratique j'ai eu quelques déconvenues (par ex., impossible d'aligner une image de la manière documentée ou de mettre en forme un tableau).
-
Hugo : essayé pour son support de reStructuredText et la documentation est très bien faite mais le support en question est plutôt bancal (ça passe par un module Python
rst2html) et à la première tentative d'insérer une image le fichier source semble introuvable mais aucun message d'erreur affiché (à cause du fait que ça passe par le module Python j'imagine). J'avais aussi considéré à Sphinx mais ça a l'air très orienté Python et la documentation est relativement imposante au premier abord (ceci dit elle doit être complète).
Bref, j'ai donc 2 grandes interrogations :
- Ai-je raison de croire que des langages de markup autres que Markdown seraient plus appropriés pour produire de la documentation utilisateur ?
- D'expérience avez-vous des générateurs de site statique à me conseiller pour rédiger de la documentation ?
Merci!
# Sphinx
Posté par MrBidon . Évalué à 1.
L'alter-ego d'Ascii doctor (mais qui vient du Python)
# Dokiel
Posté par fbn69 . Évalué à 2.
Faut comprendre la mise en place. Après ça roule.
Génère une version "site statique" et PDF.
Permet de générer plusieurs "sites" à partir des mêmes éléments. Intéressant si on a différents niveaux d'utilisateurs.
# dokuwiki et les plugins qui vont avec
Posté par NeoX . Évalué à 3.
chez nous ont utilise dokuwiki et les plugins.
on fait donc la documentation en WYSIWYG via l'interface web ou en tapant directement en markdown,
on peut aussi le faire par l'edition de fichier texte dans les dossiers.
ensuite on a des plugins d'exports ODT et PDF qui peuvent prendre un template pour toujours ajouter le logo de la société, et d'autres infos.
[^] # Re: dokuwiki et les plugins qui vont avec
Posté par Sclarckone . Évalué à 1.
J'ai essayé Dokuwiki et c'est effectivement pas mal adapté pour l'usage que je veux en faire. Avantage supplémentaire que je n'avais pas en tête : avec l'éditeur WYSIWYG c'est beaucoup plus facile de faire contribuer d'autres personnes.
Je te remercie donc avec un peu (beaucoup) de retard. :-)
[^] # Re: dokuwiki et les plugins qui vont avec
Posté par Kerro . Évalué à 2.
Il y a un éditeur WYSIWYG dans DokuWiki ? Je n'ai pas remarqué ça.
C'est d'origine ou c'est un greffon ?
[^] # Re: dokuwiki et les plugins qui vont avec
Posté par Sclarckone . Évalué à 1.
Dans la version que j'ai déployée (2017-02-19b) il y en a bien un et ça n'a pas l'air d'être un plugin (pas trouvé dans la liste des plugins installés en tout cas).
[^] # Re: dokuwiki et les plugins qui vont avec
Posté par Kerro . Évalué à 2.
Cette copie d'écran ne montre en rien que c'est du WYSYWYG. On voit juste une barre de menu.
J'ai exactement la même chose et c'est une syntaxe sous forme de texte.
[^] # Re: dokuwiki et les plugins qui vont avec
Posté par Sclarckone . Évalué à 1.
C'est parce qu'il y avait en effet un abus de langage…
C'est pas du vrai WYSIWYG, la barre de menu permet de faire la mise en page sans retenir la syntaxe. Ça rajoute les balises nécessaires dans la source mais il faut effectivement cliquer sur aperçu pour voir le rendu.
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.