Forum général.cherche-logiciel Générateur de site statique pour documentation utilisateur

Posté par . Licence CC by-sa
Tags : aucun
1
19
juin
2017

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 (page perso) . Évalué à 1 (+1/-1).

    L'alter-ego d'Ascii doctor (mais qui vient du Python)

  • # Dokiel

    Posté par . Évalué à 2 (+1/-0).

    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 . Évalué à 3 (+1/-0).

    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 . Évalué à 1 (+0/-0).

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

Envoyer un commentaire

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n'en sommes pas responsables.