Et vous, comment gérez-vous la documentation de vos services?

Hello,
Je lance un sujet car je n’ai pas trouvé de réponse en cherchant sur le forum. Vous, vous gérez comment la doc des services/formation que vous proposez aux utilisateur⋅ices finaux ?

Clairement, par défaut, la plupart des services, et Nextcloud en particulier, ont une documentation utilisateur assez austère (OnlyOffice pour le coup c’est mieux). Nos utilisateur⋅ices ne s’y retrouvent pas bien.

Alors on a essayé de proposer des sessions de prise en main (c’est chronophage), de mettre à jour une FAQ (c’est très partiel), de rediriger vers la doc (les gens s’y perdent). Du coup on se demande comment, en bon CHATON, retomber sur nos pattes :cat2: :leg:.

Les discussions qu’on avait eues lors de la visio avec @IndieHosters, @Paquerette, @Numericloud avaient fait remonter ces questions aussi.

Du coup, vous, vous gérez l’accès à la doc comment ?

3 Likes

Pour mon cas, j’héberge ma documentation dans une section de mon site
Web (un sous-dossier, à savoir https://www.automario.eu/doc/) et
j’utilise un moteur statique (MkDocs) pour la générer à chaque mise à
jour. Tu y trouves en premier des sections pour les utilisateurs (genre
synchroniser son calendrier, ses contacts, configurer son client mail,
etc) et ensuite, des sections pour les admins et les bricoleurs si tu
veux installer les serveurs et logiciels que j’utilise.

J’ai pas fait de tuto complet pour Nextcloud, car c’est long et
compliqué de tout couvrir, sans parler que cela dépend en partie de ce
que tu installes comme extensions, mais on peut utiliser le wiki des
CHATONS pour ça si jamais.

C’est vraiment super de maintenir ça, c’est vraiment clair ! On a un peu peur de se lancer là-dedans et de devoir refaire tous les screenshots toutes les deux version de NC notamment, on s’interroge aussi sur le point suivant :
Idéalement une bonne partie de la doc devrait être dispo upstream, car commune à toutes les instances Nextcloud, comment alors plutôt avoir un système de doc qui puisse présenter les modifs qu’on y a faites…

1 Like

Au PIC la documentation est disponible sur le site web de l’asso.

Pour les formation, on propose une fois par mois un atelier ouvert à tous⋅tes, pas seulement aux adhérent⋅e⋅s, sur un des services proposés (ou pas forcément d’ailleurs, j’ai fait un atelier sur Inkscape cette année, et parfois on parle de OpenStreetMap).

Une documentation mutualisée entre les chatons pourrait être une bonne idée, mais ça dépend aussi de l’état de la documentation propre pour chaque outil.
Est-ce que ça n’aurait pas sa place dans le wiki des chatons ? Il commence à y avoir pas mal d’info disponibles pour les utilisateur⋅ices, par exemple la page sur Nextcloud qui renvoie vers quelques tutoriels.

chez @infini il y a le Wiki trouvable facilement sur leur page d’accueil .
On peut y trouver ce dont on a besoin en tant qu’utilisateur. Et en plus il y a le mail et puis IRC … pour joindre la tech.
chez @tedomum il y a une page documentation qui est très détaillée visible aussi sur leur page d’accueil et un salon Matrix que je n’ai pas visité.
Voilà un retour utilisateurice de CHATONS si ça intéresse.

Je complète en indiquant que chez Framasoft, on a un site dédié à la documentation pour chaque service que l’on propose : https://docs.framasoft.org/

On met à jour régulièrement les contenus en prenant en compte les mises à jour de chaque logiciel et les retours de nos utilisateur⋅ices. Je ne saurai quantifier ce que cela représente en charge de travail, mais ce n’est pas négligeable.

Je ne crois pas qu’une documentation mutualisée entre chatons pourrait fonctionner car pour le même logiciel, il y aura toujours des spécificités propres au service du chaton (dans telle version du logiciel, avec telle surcouche, tels paramètres activés ou non) et les utilisateur⋅ices risqueraient d’être perdu⋅es.

En revanche, on pourrait récupérer sur stats.chatons.org les URL de la documentation de chaque chaton pour un logiciel et l’ajouter sur le wiki. Je crois que @antoinejaba va avoir une nouvelle mission :wink:

1 Like

Dans un monde idéal :slight_smile:

La doc serait:

  • upstream en Anglais
  • facilement traduisible
  • screenshot automatiques (Par exemple ) (réutilisable pour avoir les screenshots à nos couleurs)
  • facilement « configurable »
    • app/plugin activés/installés/désactivés
    • ajout de doc spécifique (diff? pre/post hook?)
    • themable (avoir le meme theme pour toute ses docs)
  • didactique?
    • Première lecture
    • utilisation avancée
  • différence admin/user
  • search engine
    • dans la doc
    • dans le support/forum
    • dans git?

Dans le cas de Nextcloud, la doc en Anglais mériterai déjà un peu de love :slight_smile: La partie automatisation de screenshot, c’est un bon projet geek!

Dans un mode idéal!

1 Like

Côté ARN c’est là: https://wiki.arn-fai.net/documentations
ET on fait des liens depuis COIN (l’espace adhérent) donc quand une personne demande un service dans COIN, la doc dédiée est proposée.

Ça pourrait fonctionner si un groupe de chatons se mettait d’accord sur une architecture commune qu’ils ou elles répliquent dans chaque chatons.

2 Likes

@pierre Je crois qu’on partage un peu le même idéal :).

Je rajouterais aussi : intégrée (automatiquement) à l’outil : la bonne doc s’ouvre quand on clique sur le bouton d’aide.

Est-ce que j’ai tort en disant qu’il n’existe pas d’outil qui permette de faire tout ça aujourd’hui out-of-the-box ? Est-ce que vous auriez des suggestions d’outils qui pourraient être utilisés pour commencer ? Je pense en particulier la partie « configurable ».

1 Like

intégré à l’outils, tu en demande beaucoup, si tu peux ajouter un petit ? quelque part, avec un lien c’est déjà pas mal :slight_smile:

Pense pas que cela existe.

Mon intuition, regarder les moteur de doc des cibles (RocketChat -> gitbook, Nextcloud -> sphinx avec le theme read the doc).
Dans RocketChat, tu peux choisir le dossier qui t’intéresse par exemple:


et ensuite supprimer la page dont tu n’as pas besoin:

Comme c’est un gitbook, on peut le styler d’une autre manière.

Tu peux ajouter des fichiers.

Pour insérer des phrases dans la doc, ça me parait touchy…

Et Rocket, c’est pas traduit…

Finalement, pour chaque doc, c’est un pipeline CI/CD :slight_smile: avec des scripts pour configurer comme on veut. Mais oui, si upstream change, ben… C’est toujours le même problème de comment on maintient un fork, pas de recettes magiques je pense…