Où mettre la doc technique de sysadmin ?

Bonjour à toutes et tous,

Je me questionne un peu sur "où" est-ce le mieux de mettre la documentation technique concernant des aspects de sysadmin. Les questions du genre comment installer Nextcloud, une ferme de Dokuwiki, paramétrer Apache et Nginx, etc.

Actuellement une grosse partie est sur le Wikhan, et ça me semble bien parce que le Wikhan est un wiki très généraliste, destiné à une documentation couteau suisse pour "tout" ce qui est de près ou de loin en rapport avec les objectifs de l'asso. C'est à dire "soutenir la création d'univers fictifs libres", ce qui passe par le besoin d'héberger et maintenir les outils utiles à cette création et à l'animation de communauté.

Nous avons cependant déporté notre activité "sysadmin" sur Numenaute. Ce qui est très bien aussi dans le sens où on se sent plus libre de jouer avec des services qui n'ont pas grand rapport avec Khaganat. Pour ce qui est de mutualiser avec d'autres structures c'est pas encore au point mais ça viendra peut-être. Bref, Numenaute a aussi un site, sous forme de wiki-parce-Zat, et forcément y'a un peu de tentation d'y mettre aussi de la doc. MAIS il me semble que disperser tout ça n'est pas une très bonne idée. Ceci dit, avant de faire mon autokratès, je laisse un peu de place aux échanges, car de bonnes idées peuvent émerger, ainsi que des arguments que je n'ai pas.

J'aurais tendance à garder sur le wikhan et en public ce genre de fiche :
- Documentation concernant l'installation, le paramétrage et la maintenance d'un service (logiciel)
- Documentation concernant l'usage par les utilisateurs de base, sur un service non personnalisé

Ce genre de fiche, par contre, me semble nécessaire sur chaque "instance" (Numenaute, Khaganat, etc)
- Condition d'utilisation des services, spécificité propre à une instance, RGPD associé

Enfin, ce qui reste en doc "privée" (accessible uniquement aux personnes ayant les droits pour bidouiller) :
- Documentation sur l'architecture, les paramétrages privés. Et encore dans ce dernier cas, vu qu'aucun mot de passe ne doit être en clair... mais parfois cacher au grand public le nom d'une base de donnée et le laisser dans la doc privé réduit un peu les surfaces d'attaques tout en simplifiant le travail des sysadmin.
- Doc sur les processus de sauvegardes précis (du genre, X sauvegarde Y de tel façon avec tels paramètres).

Bref, du général au particulier ; et tenter au maximum de documenter sur le wikhan avec au besoin renvoi vers les fiches génériques depuis des fiches particulières (comme par exemple sur la partie sysadmin de la fiche "pad" de Numenaute).

Bonjour,

Je suis d'accord le fait de revoir où est-ce que l'on place la documentation.

Pour ma part, le Wiki de Numenaute, que ce soit public ou privé, devrait contenir :

- Tout ce qui touche à la documentation, la gestion et l'usage de notre infrastructure et des services sauf service très spécifique (Ex : Le serveur de jeu de Khaganat).
- La documentation à destination des utilisateurs sur l'usage des services proposés par Numénaute.

Le Wiki de Khagnat garderait tout ce qui touche au projet directement (Exemple le serveur de jeu).

Ceci permettrait de facilité la gestion des sysadmins pour retrouver les informations. Je ne compte plus le nombre de fois où la cherche d'une documentation m'est devenu difficile juste parce que perdu entre Wikhan et Krypte...

Autre point à noter, si nous devions accueillir quelqu'un pour participer à Numenaute et que cette personne ne souhaite pas participer à Khaganat. Elle n'aura pas à jongler entre deux wikis de deux projets différents.

Avec ce point de vue là, la gestion de ce qui est privée ou publique peut être discutée ultérieurement je pense car, elle devient propre à chaque projet de décider de ce qui est visible ou non.

Tout ce qui suis est OK pour moi

Ce genre de fiche, par contre, me semble nécessaire sur chaque "instance" (Numenaute, Khaganat, etc)
- Condition d'utilisation des services, spécificité propre à une instance, RGPD associé

Enfin, ce qui reste en doc "privée" (accessible uniquement aux personnes ayant les droits pour bidouiller) :
- Documentation sur l'architecture, les paramétrages privés. Et encore dans ce dernier cas, vu qu'aucun mot de passe ne doit être en clair... mais parfois cacher au grand public le nom d'une base de donnée et le laisser dans la doc privé réduit un peu les surfaces d'attaques tout en simplifiant le travail des sysadmin.
- Doc sur les processus de sauvegardes précis (du genre, X sauvegarde Y de tel façon avec tels paramètres).

J'ai bien fait d'attendre, parce que les arguments de Rollniak m'ont convaincu.

Ça sera plus clair si Numenaute s'autonomise que ce soit elle qui héberge les docs.

Mais il faut dans ce cas bien faire attention à déplacer les docs, pas les copier.

Mais il faut dans ce cas bien faire attention à déplacer les docs, pas les copier.

Et espérer que sur Khaganat tout ce genre de truc a été étiqueté correctement sous le tag sysadmin. Ou autre tag de ce genre (web, serveur, bot, etc).

Et donc :
- Qui le fait ? À vue d'œil il doit y avoir une centaine de pages. Et par "qui", j'entends "les personnes qui jugent ça pertinent doivent s'engager maintenant "
- Quelle est sa date butoir ?

Par ailleurs, si sur le wikhan ce n'est pas un souci d'oublier une page d'un service qu'on ne gère plus (au pire à l'occase on collera le tag "obsolète" en y passant), est-ce que ça vous semble pertinent d'y transférer dans un nouveau wiki tel quel ? Si non, la mise à jour des informations est-elle possible en respectant la date butoir du transfert ? Et l'option "on supprime", ce sera "non", parce que hélas faut parfois revenir faire de l'archéologie sur des vieux machins qui aident à régler des problèmes plus récents et qu'il est très difficile de dire a priori "ceci, c'est ok, ça ne servira plus jamais". Vous me voyez venir : ces pages vont demander un travail en plus, puisqu'on ne pourrait pas les laisser sur le Wikhan mais qu'on ne pourrait pas les transférer tel quel sur Numenaute. Avez-vous envie de reprendre l'article de Limnoria par exemple ?

Enfin, pour quelle raison Numenaute devrait contenir de la doc technique générique, concernant parfois des services que nous ne gérons plus ?

Un exemple avec tout ce qui concerne LDAP : ça n'est pas à l'ordre du jour sur Numenaute, mais comme on l'a eu sur Khaganat, on en trouve des traces un peu partout. Je n'exclue pas qu'un jour, on réutilise LDAP sur Khaganat ou Numenaute ou ailleurs, mais pour le moment on se passe de cette couche de complexité. Alors, quelle raison pour que ce soit sur Numenaute ? Car autant Khaganat a un objet précis pouvant couvrir heuuu quasiment tout, autant le but de Numenaute est uniquement de fournir des services précis (mais pas de documenter de quoi faire des petits bateaux chatons, en tout cas ça n'a jamais été dans les buts du projet).

Ici, je rappelle l'aspect politique des deux projets :
- D'un côté Khaganat, structuré en association, avec un but précis et un champ très large
- De l'autre Numenaute, structuré assemblé selon les idées du moment et au champ très étroit, sur lequel il manque énormément de travail "non tech".

Autre point à noter, si nous devions accueillir quelqu'un pour participer à Numenaute et que cette personne ne souhaite pas participer à Khaganat. Elle n'aura pas à jongler entre deux wikis de deux projets différents.

Si on accueille des nouvelles sur Numenaute, il faudra qu'elles sachent gérer avec bien plus que ça. Les wikis d'Archlinux, Ubuntu, les docs des divers logiciels, etc

- Tout ce qui touche à la documentation, la gestion et l'usage de notre infrastructure et des services sauf service très spécifique (Ex : Le serveur de jeu de Khaganat).

Comment vous déclarez qu'un service est "très spécifique" ? Quelle est la définition précise ? Par exemple, Freescout est utilisé à 99% par MMF (et pour bien faire faudrait qu'on fasse une instance pour chaque asso, si on se met à l'utiliser avec d'autres), donc la doc liée doit être uniquement chez MMF ? Si une autre asso utilise un serveur de jeu basé sur Godot, est-ce qu'on décide alors de transférer toute la doc du serveur de jeu sur Numenaute ?

Ceci permettrait de facilité la gestion des sysadmins pour retrouver les informations. Je ne compte plus le nombre de fois où la cherche d'une documentation m'est devenu difficile juste parce que perdu entre Wikhan et Krypte...

Superkrypte tu veux dire ?

Ça, ça vient justement d'un petit souci d'organisation ; Superkrypte n'aurait dû contenir QUE les infos qui ne pouvaient pas être en public. La doc générique a été en partie transférée sur le Wikhan (mais je ne garantis pas qu'il n'en reste pas, à un moment j'ai craqué de faire de la curation). Par ailleurs, il y a un truc génial sur le web, qui s'appelle les liens hypertextes et dont il faut user et abuser sur toutes les formes de wiki, afin que l'information utile se trouve rapidement, et ça clairement c'est sous-exploité dans nos wikis. Exemple : sur l'article Proxmox dans le Wikhan, on pourrait ajouter une section pour des liens vers des détails de proxmox suivant les instances, en précisant si le lien renvoie vers du public ou privé ; et sur toute doc proxmox propre à Numenaute (les trucs pas du tout génériques) ça devrait commencer par des liens vers la doc générique et publique...

Mon objectif en lançant cette discussion est de ne pas repartir dans le même bordel, et en fait je vois bien que ça a déjà commencé, d'où la nécessité de caler les usages et utiliser les wikis proprement. Parce que jusque là, la curation, c'est surtout moi qui l'aie géré, mais depuis mon dernier burn out je n'ai vraiment plus l'énergie d'en faire autant et que si cette charge mentale n'est pas mieux gérée collectivement, ça ne marchera pas. Ni sur Numenaute, ni sur Khaganat.

Avec ce point de vue là, la gestion de ce qui est privée ou publique peut être discutée ultérieurement je pense car, elle devient propre à chaque projet de décider de ce qui est visible ou non.

Cet aspect, en fait, n'a rien d'anodin dans la rédaction d'une doc.

Pour moi, l'objectif est qu'un travail de doc puisse être utilisé par le maximum de monde. Pour info, notre doc sur le Wikhan à propos de Xen a débouché sur des propositions d'embauches de gens extérieurs au projet... Et de façon générale en fait, la doc publique du Wikhan m'aura permis de rencontrer des gens dans le milieu associatif et professionnel, qui n'étaient pas forcément happés par le côté "jeu" mais s'intéressaient aux aspects techniques variés. Je rappelle que Khaganat ce n'est pas qu'un jeu... en fait, c'est même une partie assez secondaire du projet, même si ça peut prendre de la place.

Certaines docs publiques sont de très bonnes qualités, pour le reste c'est toujours utile de trouver des astuces, sans avoir besoin de faire partie du projet (personnellement je zieute les wikis de divers projets sans en faire partie...).

Mais ce genre de choix impacte profondément la façon dont on rédige. En particulier, sur une doc publique, on donne des exemples en précisant quelle partie il faut personnaliser ; sur une doc privée on donne la configuration directe de l'infra. Lors de la rédaction même, on ne structure pas les choses de la même façon. On le voit bien au fil du temps avec Deed et moi, on ne rédige pas de la même façon nos "fils rouges" (une suite d'instructions quasi à copier coller) et nos "docs" (où on détaille pourquoi telle option, pourquoi ici ça peut buguer suivant les particularités de l'installation, etc). On a d'ailleurs tendance à faire deux fiches quand on a le temps : la doc (la vraie) et le fil rouge (la liste des commandes, et le contenu ds fichiers de config).