Journal Gestion de documentation

30
21
jan.
2019

Bonjour à tous,

Je suis devant une problématique où il me manque des outils informatique pour accomplir une tache qui me semble de l'ordre du faisable techniquement avec des briques existante. Mais avant de redécouvrir la roue, j'aimerai votre avis et retours d'expérience.

Le contexte

L'entreprise dans laquelle je suis conçois et vends des équipements industriels. Chaque équipement est unique mais repose sur des bases similaires (des plateformes identiques auxquelles on ajoute des options standardisées ainsi que des options spécifiques développées pour le client).

Avec chacun de ces équipements, on fourni une documentation extensive du matériel (plans, schémas électriques, hydraulique et pneumatiques, équipements et instruments fournis, description du soft de l'automate, manuel d'utilisation, manuel de maintenance, manuel d'installation…), qui représente plusieurs centaines de pages. Ces documents sont vérifiés et signés en interne et par le client avant et après la fabrication et font souvent l'objet de modifications (suivi par des versions, elles vérifiées et signées).

L'état actuel

Mis à part les plans et schémas qui sont sous un format spécifiques, la plupart de ces documents sont aujourd'hui créés sous MS Word à partir de documents "masters" que l'on adapte à chaque équipement. Ils contiennent cependant des schémas, tableaux et images, des entêtes et pieds de page. La montée de version des documents est suivie à la main directement dans le fichier avec un tableau à remplir.

Vous pouvez facilement imaginer les heures perdues à manipuler les fichiers, indiquer le numéro de série de l'équipement sur l'ensemble des documents, l'oubli d'éléments liés à telle ou telle option dans tel ou tel document, les erreurs possibles lorsque les masters utilisés ne sont pas à jour où lorsque l'on souhaite faire un équipement quasi identique à un ancien projet (et que le master utilisé pour celui-ci date). Les montées de versions aux modifications non tracées, etc… La difficulté de vérifier une nouvelle version car on n'a pas la trace exacte des modifications…

Mon souhait

La problématique m'a immédiatement fait penser à l'idée que je me fait du développement d'un programme informatique à l'aide de git.
On a un master qui contient l'ensemble des options existantes, à partir duquel on crée des branches (chacun des équipement unique). Dans ces branches on sélectionne les options standardisées et on y ajoute les options spécifiques à cet équipement.
Dans le cas où le master évolue, on pourrait faire des fusions afin d'appliquer ces "commit" à l'ensemble des branches qui en auraient besoin.
De plus les différentes versions des documents pourraient représenter des tag. On pourrait même gérer la signature du document (équivalent des revues de code).
Je rêve donc d'un système où, en sélectionnant la plateforme de base, les options standardisées,

Mon souci

Aujourd'hui j'imagine que si j'étais seul, je créerai un dépot git, quelques scripts python pour fusionner des fichiers décrivant chaque options écris avec un format plain text (du type markdown). Et un fichier de config qui serait dans chacune des branches pour sélectionner les options.

Seulement je ne suis pas seul, et les collègues qui travaillent sur ces dossiers ne sont pas familiers avec les outils de versionning propre à l'informatique. De plus je souhaiterais avoir un système qui ne repose pas tout entier sur moi pour le développement et le support. Pour de multiple raisons (pas maintenable si je quitte la boîte, donc ne sera pas accepté, et je ne suis pas développeur, je me lance dans ce projet car je souhaite améliorer l'existant, pas parce que c'est ma tâche).

L'édition des documents doit pouvoir se faire avec un outil WYSIWYG. Mes collègues ne sont pas non plus totalement réfractaires à gérer les fichiers de façon différente (découper par option, etc…), mais aller sur du balisage et une gestion des images complexe serait rédhibitoire.

La question

Du coup je me tourne vers vous pour voir si vous connaissez des outils de gestion de documentation qui pourrait correspondre plus ou moins à ce que je recherche, ou du moins des pistes pour avancer ou en faire une partie.

Désolé pour le long journal, j'ai souvent tendance à rentrer dans les détails pour être bien compris.

Voici un peu ce que j'ai farfouillé pour l'instant, en vrac :
Simul : https://www.simuldocs.com/ => propriétaire et au fonctionnement un peu obscur, pérenne dans le temps ?
Publication : Weasyprint => comment l'intégrer dans le workflow ? Ecrire les documents en html ?
Versionning : git et pandoc http://hrishioa.github.io/tracking-word-documents-with-git/ => manque la notion de merge

Nota: Je suis ingénieur en mécanique et je ne suis pas développeur. J'utilise git pour des petit projets perso car je programme un peu dans mes temps libre, mais de façon très basique avec seulement 1 utilisateur.

  • # Wiki

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

    Personnellement je regarderai du côté des wiki évolués (contrairement aux wiki minimalistes). Je pense en particulier à XWiki. Je ne sais pas à quel point ça peut te convenir ou pas.

  • # etherpad, wiki, Lyx, ...

    Posté par (page perso) . Évalué à 5 (+3/-0). Dernière modification le 21/01/19 à 20:03.

    J'aurai tendance à me tourner vers des outils avec des formats de documents textuels qui sont faciles à versionner. Par exemple Lyx.
    Mais pour ne pas tout réinventer, un Etherpad façon Framapad ou un Wiki sont assez puissant et déjà versionnés.
    Wikipedia a plein de bots pour automatiser le (re-)classement, ça doit pouvoir gérer ton bidule. Pour la fusion de parties de documents, c'est ce qui est fait dans le projet Wikisource.
    XWiki, comme dit plus haut, est très très bien aussi.

    Enfin, as-tu regardé les outils de GED ?

    "La liberté est à l'homme ce que les ailes sont à l'oiseau" Jean-Pierre Rosnay

    • [^] # Re: etherpad, wiki, Lyx, ...

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

      Je viens de regarder Etherpad, je vois en quoi il réponds aux besoin de suivi des changements et gestion des versions, je ne vois pas comment il peut résoudre le coté document master, branching et fusion.

      Je vais regarder un peu plus du côté des Wiki, mais ça me semble quelque chose de très lourd à gérer, j'aurais préféré une solution où l'on reste sur des documents qui vivent dans des fichiers séparés et éditable directement, le fait que les documents vivent dans une base de donnée quelque part ne m'attire pas du tout.

  • # git

    Posté par . Évalué à 4 (+3/-1).

    la courbe d'apprentissage est assez forte pour que tous le monde puisse maitriser le sujet, j'eusse tenter de convaincre la direction de passer a tortoiseSVN + markdown mais le regard vide de mes collaborateur qui pensaient que je me faisait chier pour rien car word le fait très bien sans se prendre la tête, m'a un peu refroidi.

    je l'utilise que pour mon poste de travail et mes document dit de travail, à mon grand regret.

    visiblement vous êtes ISO 9001, tu est censé faire une proposition d’amélioration en suivant une procédure, fait un joli document pour leur montrer les possibilitées, tu verra si ça passe. il faudrait un POC mais ca demande du boulot. mais les vois tu ouvrir une console pour lancer des commandes git ?

    • [^] # Re: git

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

      Justement je ne les vois pas ouvrir une console et lancer du git. C'est bien pour cela que je cherche des outils.

      Quand à suivre la procédure ISO, bien entendu je fais ça tout les jours, mais il faudra bien d'abord trouver un concept qui tiens la route.

  • # Tracim avec éventuellement module dédié ?

    Posté par (page perso) . Évalué à 10 (+14/-0).

    Disclamer : je suis le responsable du projet tracim.

    Je pense que git en terme de fonctionnalités répond à tes besoins d'un point de vue fonctionnalités. Par contre, si tu as besoin d'outils confortables, il faut une interface au dessus de git et de son versionning.

    Développant tracim pour ce type de problématique (versionning, collaboration et simplicité de prise en main), je pense que Tracim correspond "presque clé en main" à cela :

    • tu mets l'ensemble de tes documents standardisés (principaux et optionnels) dans une arborescence définie et figée. Le versionning est natif dans tracim, donc pas de question à ce poser par rapport à cela.
    • tu crées une branche d'arborescence dédiée aux options sur mesure.

    Chacun de tes documents va évoluer à son rythme via les éditions des différents collaborateurs. Un équipement est une combinaison de documents standards ou spécifiques, chacun dans une version spécifique.

    Je vois 3 manques potentiels dans cette solution :

    • le fait de mettre des tags "nommés" sur des versions de document (le versionning de tracim est suffisant techniquement, mais il ne permettra pas d'avoir des tags explicites, juste des numéros de version)
    • la configuration de la représentation d'un équipement (combinaison de l'ensemble des versions de chaque document).
    • un outil pour agréger les documents dans les versions requises.

    Je vois du coup deux concrétisations possibles de ton projet avec tracim :

    • tu définis qqpart un fichier yaml ou json qui définit quels documents sont utilisés pour documenter tel équipement et quelle version de chaque document, et tu as un script qui récupère l'ensemble des documents via l'api REST de Tracim. Toute l'édition et l'historisation est faite via l'interface graphique et le script se charge juste de rappatrier les bons éléments de documentation,
    • tu fais la même chose avec une application tracim faite sur mesure qui se charge de faire le travail d'agrégation et le stockage des configurations de documents. Dans ce cas tout est graphique (mais il faut faire + de développement).

    Dans les 2 cas on (la société algoo, derrière tracim) peut t'accompagner. Dans le premier cas au vu de ce que tu dis, ça ne me semble pas nécessaire : tu développes, tu as les compétences pour faire les bons appels d'API et configurer / stocker / parser un fichier de description en yaml/json. On pourra te faire gagner du temps en t'accompagnant ; tu pourras aussi t'en sortir seul. Dans le second cas, ça me semble plus avancé comme développement (modèle supplémentaire en base représentant une configuration + application sur mesure). La seconde solution est pour moi une évolution naturelle de la première : tu valides le concept avec un script "bricolé", et une fois que le prototype est validé, tu fais l'interface sur mesure adaptée au quotidien.

    Par rapport à ce que tu évoques, il y a des avantages en terme d'ergonomie et de fonctionnalités dans tracim : fichiers (uploadés) et documents rédigés sous forme de wysiwyg sont au même endroit. Les images intégrés dans tracim sont directement intégrés en glissé/déposé. Tout est versionné ; tu pexu identifier le statut de chaque document.

    Pour en savoir plus sur tracim : https://www.tracim.fr/demo (video de 2 minutes et démo accessible et testable directement en ligne)

    • [^] # Re: Tracim avec éventuellement module dédié ?

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

      Cette solution me semble intéressante selon certains aspects.

      Quelques questions :

      Où vivent les documents ? Dans des bases de données ? Si non, sont-ils des documents directement utilisables en temps que tel ? Y a-t-il une arborescence conservée dans des dossiers ?

      le fait de mettre des tags "nommés" sur des versions de document (le versionning de tracim est suffisant techniquement, mais il ne permettra pas d'avoir des tags explicites, juste des numéros de version)

      Une version est créée à chaque modification du document ?

      • [^] # Re: Tracim avec éventuellement module dédié ?

        Posté par (page perso) . Évalué à 5 (+3/-0).

        Quelques questions :

        Où vivent les documents ? Dans des bases de données ?

        Historiquement on stockait les fichiers en base, pour avoir une seule source de vérité. En terme de performance ce n'était pas idéal, en terme de sauvegarde c'était mauvais (des fichiers, on peut facilement stocker un diff, une base c'est plus compliqué).

        Donc les fichiers sont stockés sous forme de fichiers, dans une arborescence spécifique, non exploitable directement (ils sont stockés avec un hash, et les infos en base permettent de faire le lien)

        Si non, sont-ils des documents directement utilisables en temps que tel ?

        Les documents ne sont pas directement utilisables, mais tracim propose une interface webdav. Cette interface permet d'accéder à la dernière version des documents, et les modifications génèrent automatiquement un versionning. Cette interface représente fidèlement l'arborescence définie pour l'organisation des données.

        Y a-t-il une arborescence conservée dans des dossiers ?

        Comme évoqué, les fichiers sont stockés d'une certaine manière, qui n'est pas l'arborescence déterminée par les utilisateurs. Pour en savoir plus, tracim s'appuit sur depot pour le stockage.

        Comme dit au dessus, l'interface webdav permet d'accéder aux fichiers sous forme de dossiers et fichiers et contenus comme avec n'importe quel explorateur de fichier.

        En complément, une personne travaille chez nous sur l'implémentation d'un client de synchronisation, ce qui permettra d'avoir en local sur un poste client (ou sur un autre serveur) une copie conforme de l'arborescence complète des contenus, ainsi qu'une synchronisation bi-directionnelle (on devrait avoir un prototype d'ici quelques temps, la première version stable devrait être pour l'été).

        Une version est créée à chaque modification du document ?

        Oui. C'est automatique.

    • [^] # Re: Tracim avec éventuellement module dédié ?

      Posté par . Évalué à 4 (+2/-0). Dernière modification le 22/01/19 à 17:17.

      Je viens de tester tracim que je ne connaissais pas

      C'est super sympa, joli, rapide, facile à utiliser
      juste un truc : comment on imprime ou on genere un PDF depuis tracim ?

      • [^] # Re: Tracim avec éventuellement module dédié ?

        Posté par (page perso) . Évalué à 6 (+4/-0).

        Je viens de tester tracim que je ne connaissais pas

        C'est super sympa, joli, rapide, facile à utiliser

        Merci :) La version que tu as visualisé est sortie en novembre, on a une déêche en cours de rédaction (chez nous, pas encore dans la tribune de LinuxFR).

        juste un truc : comment on imprime ou on genere un PDF depuis tracim ?

        Actuellement, on peut générer le PDF d'un fichier à partir des boutons en haut de la prévisualisation (sous la barre de titre du fichier. On supporte +/- 150 formats de fichiers grâce à preview generator qu'on a développé pour l'occasion et qui s'appuie sur libreoffice, inkscape et image magic pour générer les jpeg et pdf.

        Pour les documents texte édités en ligne on n'a pas encore implémenter l'export en PDF.

  • # Markdown…

    Posté par (page perso) . Évalué à 5 (+3/-0). Dernière modification le 21/01/19 à 22:47.

    Pour avoir mené une expérience similaire (du Markdown dans des mains de non-geek), je pense que c'est une mauvaise idée.

    Pour autant, je ne rejette pas la faute sur les utilisateurs, mais plutôt sur le Markdown, qui est finalement un langage beaucoup moins simple qu'il n'y paraît quand il s'agit de faire des listes imbriquées, des listes numérotées avec plusieurs paragraphes (« mais pourquoi ça me numérote à 1. alors que j'ai mis 2. ???? »), etc. Les réponses sont toujours du type « faut sauter une ligne » ou « fallait rajouter 4 espaces au début de chaque ligne ».
    D'autre part, il faut trouver un éditeur Markdown qui permette les correcteurs orthographiques, ce qui n'est pas évident, et un rendu temps réel bien synchronisé (j'ai souvent des décalages verticaux entre l'interface de saisie et l'aperçu du rendu).

    De mon côté, c'est encore du Markdown mais je pense partir sur du « HTML » avec ckeditor. Je mets les guillemets car c'est un HTML très expurgé qui devrait interdire de faire n'importe quoi (je veux forcer un style très uniforme des documents) et une conversion facile vers d'autres formats.

    • [^] # Re: Markdown…

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

      C'est exactement ce qui me fait peur avec tout les langages à balise.

      S'il est agréable d'avoir des documents clean et au comportement prévisible, je pense qu'il est préférable d'avoir une approche "sale" à la Word qui autorise quelqu'un a faire de la mise en page dégelasse à base d'espace et de tabulations. Au moins la personne est autonome. Ça autorise aussi facilement d'accepter une nouvelle personne dans l'équipe (intérim, remplacement maladie, etc…).

      J'imagine que mon seul souci est de vouloir le meilleur des deux mondes.

      • [^] # Re: Markdown…

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

        Dans mon cas :
        - j'ai la chance d'avoir des utilisateurs obéissants et de bonne volonté à défaut d'être geek,
        - ils savent qu'ils n'ont aucune chance de repasser à Word ou LibreOffice (ils ont eu une phase transitoire avec LO, et leur réaction face à Markdown a été unanime : c'est toujours mieux que LO),
        - un éditeur WYSIWYG (style Word) pourrait très bien être castré pour se limiter à un sous-ensemble simple et donc obtenir un rendu homogène ( https://ckeditor.com/docs/ckeditor5/latest/examples/builds/document-editor.html ),
        - il est illusoire d'utiliser git sur du Markdown et espérer avoir en permanence du texte valide lors d'une fusion (des étoiles ou des underscores sur deux lignes différentes, par exemple) — on se retrouve à égalité avec du HTML à ce niveau : de toute façon, si tu ne peux pas garantir que la transformation vers le produit final est viable, on se moque de pouvoir faire un diff.

        • [^] # Re: Markdown…

          Posté par . Évalué à 3 (+1/-0). Dernière modification le 23/01/19 à 08:45.

          Du coup si c'est impossible de faire des merge et des diff, quel est l'intérêt que tu as trouvé à imposer Markdown à ton équipe à la place de Word ? (au cas où tu penses que cette question est du troll, c'est l'inverse, je suis vraiment intéressé par le gain d'un Markdown sur du WYSIWYG)

          • [^] # Re: Markdown…

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

            Ah non, je ne le prends pas du tout pour du troll :)
            En fait, de mon côté, les vraies contraintes étaient différentes car je voulais entre autres :

            • limiter les applications métier à utiliser,
            • du versioning (simple, sans chercher à pinailler par ligne),
            • imposer un style très uniforme en fonction du type de document,
            • personnaliser à ma manière les impressions faites,
            • permettre de lier des méta-données (qui proviennent d'une application web) à ces documents et les ajouter à l'affichage ou à l'impression.

            Au final :

            1. Intégrer l'éditeur de texte à l'application web a été la solution de moindre coût pour permettre ces points,
            2. utiliser un éditeur Markdown a été la solution à moindre coût pour permettre une mise en forme minimale (avec la possibilité de tags propriétaires et de notes de bas de page),
            3. la transformation en LaTeX a été la solution à moindre coût pour imprimer les documents avec un rendu correct1,
            4. cela permet de tout faire dans une seule application web.

            D'un point de vue technique, je me moque totalement des autres choix (WYSIWYG, WYGIWYM ou à balises), ce sont les utilisateurs (dont je suis également) qui choisiront, mais si je peux proposer un WYSIWYG qui remplisse tous mes critères, les utilisateurs seront les plus heureux du monde.


            1. J'ai bien regardé weasyprint et je m'en sers d'ailleurs pour d'autres usages, mais il ne gère pas les notes de bas de page et c'est éliminatoire. 

            • [^] # Re: Markdown…

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

              J'ai mis trop longtemps pour éditer mon message, alors je me réponds pour compléter :

              Concernant le git, je ne suis donc pas concerné mais je pense que c'est illusoire de penser que la fusion fonctionnera mieux que sur du HTML sous prétexte que les balises s'écrivent **toto** et non <strong>toto</strong> .

  • # DITA

    Posté par . Évalué à 7 (+7/-0). Dernière modification le 21/01/19 à 23:44.

    Pour ce problème dans ma boite nous utilisons un logiciel qui est basé sur la norme [DITA].
    C'est peut-être une piste à creuser.

    Je ne peux pas donner le nom du logiciel en question car je ne m'en souvient plus (je n'ai pas encore eu a m'en servir).
    Celui utilisé par ma boite contient un éditeur, une base de données pour stocker les contenus, les modèles (template) ainsi que les caractéristiques de chaque version du produit et il gère la production des documents finals.

    Il semble avoir convaincu plusieurs collègues mais il n'est pas libre.
    Apparemment il existe des briques libres qui peuvent être utilisés pour obtenir un résultat similaire.
    https://www.dita-ot.org/
    Je n'ai pas testé.

    • [^] # Re: DITA

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

      C'est exactement ce que je recherchais comme retour à mon journal : des retours concrets de boîtes qui ont le même besoin. Je me doutais que l'on était pas la seule entreprise à écrire de la documentation.

      Je vais regarder ce DITA de plus près et voir si ça correspond à ce que je recherche.

      Merci !

      • [^] # Re: DITA

        Posté par . Évalué à 1 (+0/-0). Dernière modification le 25/01/19 à 08:28.

        J'avais vu une interview du patron de CaptainContrat qui a cette problématique, c'est même au cœur de leur stratégie. De mémoire, réglée à coup de XML et de Word généré. Dommage qu'il ne publient pas leurd outils. Et ils sont une bonne armée de devs avec du support de Microsoft.

  • # scenari

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

    La chaine éditoriale scenari ?
    https://scenari.org

    Séparation des contenus et des modèles
    Modèles pour édition vers doc en ligne / pdf /papier ….. à partir d'un même contenu
    Travail seul ou en équipe pour la gestion des contenus et/ou des modèles

    Avec notamment la chaîne de rédaction de documents techniques
    https://scenari.org/co/4_B_1_Dokiel.html

    Logiciel libre : https://scenari.org/co/1_B_1_LogicielLibre.html

    On avait approché cet outil pour notre service, il y a quelques années pour des besoins similaires.

    • [^] # Re: scenari

      Posté par . Évalué à 1 (+1/-0). Dernière modification le 22/01/19 à 11:55.

      +1
      J'utilise Dokiel pour de la documentation de logiciels. Ca correspond au besoin, sauf peut-être au niveau versioning.

      Site de Dokiel

      • [^] # Re: scenari

        Posté par (page perso) . Évalué à 3 (+0/-0).

        Je me suis permis d'éditer le commentaire pour corriger le lien vers le Site de dokiel.

      • [^] # Re: scenari

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

        Bonjour.
        Je suis un des concepteurs historique de Scenari, j'ai travaillé en ingénierie documentaire sur ces problèmes pendant longtemps. Je voulais prendre le temps de répondre un peu à tout, mais à défaut je prends celui de poser quelques notes :
        - Scenari est fait pour cela, et existe dans une version collaborative qui permet de gérer historisation, versionning, diff, workflow… C'est libre. Il y a des modèles libres prêts à l'emploi, comme Dokiel en effet et on peut développer les siens. Il existe une Scoop française, kelis.fr qui accompagne si besoin (ce sont des amis, mais je ne travaille pas dans la société).
        - Si l'on veut de l'écriture structurée, et il y plein de bonnes raisons d'en vouloir, les solutions "bâtardes" à base de Markdown ou de bureautique "castrée" ne fonctionnent pas à moyen terme en général : le coût de gestion des erreurs a posteriori est supérieur au coût du changement a priori (sauf cas très récalcitrants, mais ce n'est pas le cas ici). Donc quand on peut poser un bon schéma de contrôle déterministe c'est l'idéal !
        - Il y a plein de réalisations industrielles qui montrent ça aujourd'hui (http://scenari.kelis.fr/co/references.html)
        - Si certains veulent un peu de "théorie", j'ai posé des choses ici par exemple : http://aswemay.fr/co/010024.html
        - Et quelques exemples de fonctions ici : http://aswemay.fr/co/010027.html
        - Concernant DITA, Docbook et autres schémas standard, c'est un débat légitime, pour ma part je crois plus à l'agilité des schémas locaux, mais si l'interopérabilité avec des tiers qui utilisent un schéma standard est un enjeu fort, c'est à étudier (écriture native DITA ou Docbook ou import/export typiquement). Dans notre expérience, c'est toujours le schéma local qui a été favorisé pour son adaptation aux usagers.

        Et n'oublions pas que « Notre Word lui-même fit beaucoup pour enlever à la vérité et à la beauté l'importance qu'on y attachait, et pour l'attacher au confort et au bonheur. » (presque A. Huxley)
        Stéphane.

    • [^] # Re: scenari

      Posté par . Évalué à 0 (+0/-0). Dernière modification le 01/02/19 à 08:15.

      -

  • # Gestion documentaire de ligne de produit

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

    Ce que tu veux faire s’apparente à de la gestion documentaire de ligne de produit (product line management).

    J'ai utilisé un produit propriétaire pour faire cela il y a longtemps (Rational DOORS avec les plugin T-REK et IRDRMFAO). C'est propriétaire, très cher, lourd donc je déconseille. Mais ça le mérite de donner une idée des besoins fonctionnels, donc j'en parle ici.

    Justement, au niveau fonctionnel c'est une base de données relationnelle avec une interface graphique (réinventée sous la forme de DOORS) par dessus laquelle on ajoute de la numérotation d'éléments et de la génération documentaire (T-REK), de la gestion en version et de commentaires (RCM), en branches et de paramétrisation des éléments (PFM). L'idée est au final de pouvoir générer par exemple la spécification fonctionnelle du bateau à moteur ou à voile à partir de la même base de données tout en partageant la description de la cuisine ou de la distribution électrique sans copier-coller.

    Je n'ai pas connaissance d'outil libre qui réponde à ce besoin.

    Le problème que tu décris me semble commun dans tous les métiers de production documentaire technique (peut-être au-delà mais je connais moins) où une documentation évolue et doit être maintenue et reprise pour un nouveau produit ou pour gérer la maintenance d'une spécification.

    Si j'avais du temps et encore l'espoir que mon monde professionnel envisage autre chose que Word ou similaire pour produire la documentation technique, je partirai sur une interface Web par dessus git+pandoc et quelques balises supplémentaires pour gérer la numérotation des élements (type exigences), et l'annotation de parties génériques dans la documentation ou de parties spécifiques. Gitlab Web Editor serait en ce sens assez proche mais il manque une extension de langage et quelques scripts pour produire les documents et définir une sorte d'héritage entre les documents.

  • # LibreOffice + WebDAV

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

    Je suis devant une problématique où il me manque des outils informatique pour accomplir une tache qui me semble de l'ordre du faisable techniquement avec des briques existante.

    Je vais commencer par te dire que ton problème il n'est pas — je pense — principalement technique, mais humain. Si tu ne tiens pas énormément compte du facteur humain dans ta solution, ça foirera à coup sûr.

    La solution que je te propose, je l'ai mise en place pour des gens qui ne voulaient pas décoller d'un outil Word-like, ce qui sera sûrement le cas pour toi. Saches que mon expérience a été un échec complet, parce que je n'ai pas dû prendre en compte assez le facteur humain, malgré une prise en compte aiguë des contraintes techniques (compatible Windows, sans déranger les habitudes). Donc peut-être à ne pas suivre, mais comme ça ressemblait à ton problème, je viens en témoigner ici.

    Un prérequis était de travailler en groupe à distance, comme à peu près tous les outils aujourd'hui, même si aucun ne me satisfait toujours aujourd'hui (éternel problème). Pour ça, et pour éviter trop d'envois par e-mail (car c'est inévitable, ça arrivera) ainsi que les copies locales pas à jour, j'ai mis en place un partage WebDAV qui contient les fichiers sur lesquels travailler. Ça se monte bien sous Windows si on veut, et surtout ça s'ouvre directement dans LibreOffice et permet l'enregistrement direct avec le bouton « enregistrer ». Ça peut paraître un détail mais ça compte beaucoup dans l'acceptabilité utilisateur.

    Et donc ensuite, il faut travailler avec LibreOffice, mais avec une particularité : les documents inclus dans le document « final », comme les images, les schémas, voire les sous-chapitres si tu le fais en mode « bien fait », doivent être inclus en précisant de ne pas inclure les données dans le document. Ainsi, seule une référence (relative) sera faite, et on pourra ainsi mettre à jour les images/schémas sans avoir à faire de la ré-inclusion dans le document maître. C'était un des besoins, pour ne pas avoir à se retaper des inclusions à chaque fois. En pratique, ça marche assez mal parce que les dimensions des contenus sont quand même enregistrées dans le document maître, et si tu modifies le ratio ça apparaît déformé. Également, ça ne permet pas de copier-coller le document dans un e-mail, vu qu'il ne contient pas toutes les images… Bref, c'était une « bonne idée » au départ, mais en pratique ça merde trop.

    Et comme moi je bossais avec un montage davfs et qu'en plus je voulais du git, j'avais ajouté un script marrant : un cron tournait toutes les heures pour voir les modifications du répertoire faites en WebDAV, et créait un commit du nom de l'utilisateur qui avait modifié le ou les fichiers. Ainsi, moi je bossais en git (avec un hook post-push qui checkout automatiquement les modifications dans le partage WebDAV) et les modifications des autres apparaissaient également dedans. Ça n'est pas complètement dans l'esprit traçable et textuel de git (bien qu'en utilisant du Flat ODF pour ce dernier point, ça aurait pu le faire, mais là j'en demandais malheureusement trop), mais ça faisait l'affaire.

    Alors là-dedans je ne parle pas du tout de branche, car je n'en avais pas, et que ça ne faisait pas partie de nos problématiques. Pour ton cas, je ne sais pas trop comment faire, mais du git même en graphique sous Windows était complètement hors de portée de mon public. En adaptant la solution ci-dessus avec un répertoire différent par branche (un working-tree par branche) ça pourrait éventuellement se faire, je pense, en réservant les opérations de merge au « spécialiste » qui utilise git, et les utilisateurs lambda qui choisissent le bon répertoire. Mais bon, ça peut sembler alambiqué.

    Sachant que tout ça ne passe pas le test du « ça ne doit pas reposer sur une seule personne », ce qui sera donc sûrement également rédhibitoire.

    Au final, le problème pour moi est bien plus profond : il est très difficile de faire ce genre de chose de manière bien structurée avec des outils WYSIWYG, et seuls les langages structurés basés sur du texte peuvent réellement résoudre le problème. Malheureusement on a « décidé » d'éduquer notre population à l'utilisation d'outils fermés et privateurs WYSIWYG, et nous payons aujourd'hui très très cher cette dépendance. C'est comme si la population aujourd'hui n'avait pas appris à écrire, et dépendais de la médiation de grand éditeurs américains pour s'exprimer. En fait, c'est même exactement la situation actuelle.

    • [^] # Re: LibreOffice + WebDAV

      Posté par . Évalué à 2 (+0/-0). Dernière modification le 22/01/19 à 13:30.

      Sans passer par un Webdav, nous avons aujourd'hui déjà simplement des dossiers sur un serveur sur le réseau dans lesquels chaque projet vit. Chaque personne édite les documents directement dessus, et personne ne conserve de copie locale ou ne les envoie par email. Ça s'ouvre directement dans Word et se sauvegarde directement dessus.

      Je ne comprends pas bien l'intérêt d'un Webdav par rapport à la solution actuelle.

      Je suis par contre d'accord avec toi que le problème est de l'ordre des connaissances des utilisateurs. Par contre je ne suis pas d'accord avec toi qu'un bon outil ne pourrait résoudre le problème.
      Word est un très bon outil, fiable, efficace et facile à utiliser. Les utilisateurs seraient sans aucun souci capable de s'adapter à un autre outil si il fournissait la même facilité d'utilisation. Mais Markdown ou autres langages à balise ne sont juste pas au niveau de ce côté là.

      • [^] # Re: LibreOffice + WebDAV

        Posté par . Évalué à 2 (+0/-0). Dernière modification le 22/01/19 à 13:45.

        Je ne comprends pas bien l'intérêt d'un Webdav par rapport à la solution actuelle.

        Ah pardon, je n'avais pas saisi que le contexte était une entreprise déjà bien équipée point de vue partage de fichier. Dans ce cas, très bien ; mon cas était pour des participants internes et externes, où WebDAV peut répondre au partage distant plutôt bien (pour des fichiers pas trop gros).

        Word est un très bon outil, fiable, efficace et facile à utiliser.

        « Fiable » à long terme, je ne pense pas, se basant sur des formats pseudo-ouverts changeant. Mais sinon oui, il est très facile et pratique, mais tu ne pourras jamais rien contrôler ni espérer à long terme avec. C'est comme tu veux, mais si tu aimes les montages « maison », tu es condamné à devoir suivre ad vitam æternam.

        Les utilisateurs seraient sans aucun souci capable de s'adapter à un autre outil si il fournissait la même facilité d'utilisation.

        Oui et non : les détails sont très importants, et parfois des choses qui te semblent anecdotiques feront tout foirer. Rien qu'en partant du format de fichier, même si ça n'est pas anecdotique du tout, et de l'effet réseau que ça engendre. Je suis désolé mais personne ne se passera de Word, si je flaire bien le public auquel tu sembles avoir à faire.

        Mais Markdown ou autres langages à balise ne sont juste pas au niveau de ce côté là.

        Heu, comment veux-tu la même « facilité » que Word avec un langage textuel ? Bien sûr que ça ne sera jamais aussi « facile » en faisant l'hypothèse d'une éducation au WYSIWYG et la supposition d'une incapacité au textuel (qui n'est pas fausse, mais l'éducation pourrait changer à long terme). Je ne comprends pas à quoi tu penses si tu imagines un langage à balise « au niveau » ? (perso si les personnes sont un peu techniques, le HTML pourrait limite être envisageable)

        • [^] # Re: LibreOffice + WebDAV

          Posté par . Évalué à 4 (+3/-1).

          On crache beaucoup sur Word et le WYSIWYG, mais c'est tout de même ce qui se fait de plus proche à l'utilisation d'un stylo et d'une feuille de papier. Il faut arrêter de vouloir tout ramener à que l'utilisateur a été déformé par le méchant Microsoft. Un traitement de texte WYSIWYG est quand même beaucoup plus abordable et intuitif qu'un langage à balise.

          Heu, comment veux-tu la même « facilité » que Word avec un langage textuel ?

          Je n'ai pas vraiment dit que je souhaitais un langage textuel. Je souhaite un système qui me permette de gérer la documentation des machines, à partir de master, d'options, avec une gestion des versions des documents à chaque validation.
          Le côté langage textuel est uniquement un aspect pour la technique qui est pour moi plus un obstacle qu'une aide.

          • [^] # Re: LibreOffice + WebDAV

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

            On crache beaucoup sur Word et le WYSIWYG, mais c'est tout de même ce qui se fait de plus proche à l'utilisation d'un stylo et d'une feuille de papier.

            Tout à fait d'accord.

            Il faut arrêter de vouloir tout ramener à que l'utilisateur a été déformé par le méchant Microsoft.

            Bah quand même… N'as-tu pas remarqué que c'est toujours le point bloquant ?

            Un traitement de texte WYSIWYG est quand même beaucoup plus abordable et intuitif qu'un langage à balise.

            Je n'ai jamais dit le contraire. Mais si tu veux faire du structuré avec suivi, etc, comme tu le veux, ça ne peux pas marcher, en dehors d'éventuelle solution made in MS tout intégrée (ça doit exister je pense).

            Je souhaite un système qui me permette de gérer la documentation des machines, à partir de master, d'options, avec une gestion des versions des documents à chaque validation.

            Avec un contrôle graphique style Word, je ne vois pas comment ça peut se faire. Mais tant mieux si quelqu'un arrive à trouver un truc qui existe.

            • [^] # Re: LibreOffice + WebDAV

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

              Bah quand même… N'as-tu pas remarqué que c'est toujours le point bloquant ?

              Étant ingénieur en mécanique, j'ai une approche pragmatique des outils. Si les utilisateurs à qui on destine l'outil n'arrivent pas à l'utiliser, c'est que l'outil n'est pas adapté.

              Je ne parles pas ici d'un utilisateur en particulier, mais d'un profil d'utilisateur. Mes utilisateurs ici ne sont pas des informaticiens, ils sont avant tout concepteurs en mécanique, hydraulique, électrotechnique, etc… Et c'est ces compétences là que l'on va rechercher lorsqu'on va les recruter.

              L'outil doit s'adapter à eux, et non pas l'inverse.

              • [^] # Re: LibreOffice + WebDAV

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

                Si les utilisateurs à qui on destine l'outil n'arrivent pas à l'utiliser, c'est que l'outil n'est pas adapté.

                Tu n'as pas dû comprendre alors ce que sont l'effet réseau et le poids de l'habitude : le premier fait que c'est difficile d'être le vilain canard qui veut une solution mieux et/ou différente de l'existant, et le second fait que changer d'outil est très chiant, même si on te présente un nouveau « plus adapté ». En fait dans le second cas, la personne qui propose un outil soit-disant mieux adapté ne se rend souvent pas compte des déficiences de sa solution par rapport à l'existant. Et dans le cas de Word, personne n'arrivera jamais à remplir tous les besoins, y compris (et surtout !) les détails, que ses utilisateurs attendent d'un traitement de texte. Appelle ça du formatage ou autre, mais c'est comme ça.

                Je ne connais pas ton expérience dans l'acceptabilité de solutions alternatives, mais pour l'observer depuis plus de 20 ans, tu n'as aucune chance si tu veux faire du simili-Word avec autre chose. Tu cherches une solution impossible.

                • [^] # Re: LibreOffice + WebDAV

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

                  Je ne partage pas en totalité ton analyse. Dans mes différentes boîtes j'ai souvent vu des transitions d'outils qui se sont certes plus ou moins bien passées, mais qui au final ont été adoptées et utilisées. Que ce soit par exemple l'adoption de Sharepoint pour le partage des documents, OneNote pour les comptes rendus de réunion jusqu'au changement d'ERP, etc… Cela montre que lorsqu'on fourni un outil adapté, les utilisateurs ne sont pas totalement réfractaires et franchissent le pas.

                  Mon constat est juste que de nombreuses personnes crachent sur Word, mais personne n'est capable de fournir une alternative viable en face. XML, LateX ou Markdown sont juste trop en deçà au niveau fonctionnalité et facilité de prise en main, et nécessitent un effort trop important pour l'utilisateur sans bénéfice réel à leurs yeux.

                  Cependant je ne cherche pas à remplacer Word totalement mais seulement pour l'application spécifique de la gestion de documentation technique, et je constate (grâce aux nombreuses réponses à ce post) que de nombreuses industries se tournent vers d'autres solutions (DITA, etc…). Je pense donc que c'est du domaine du possible d'appliquer la même chose chez moi.

                  Reste à trouver l'outil le mieux adapté à mon besoin.

  • # LibreOffice + secretary

    Posté par (page perso) . Évalué à 6 (+4/-0). Dernière modification le 22/01/19 à 14:23.

    J'ai essayé il y a 2 ans de mettre en place un système de génération notes de publication, et j'avais découvert secretary. Le principe: tu utilises un fichier OpenDocument classique dans lequel tu as des données variables dans du json ou du yaml à côté. Avec secretary, qui se base sur le moteur de templates jinja2, tu remplaces les données dans le document. Ainsi les données variables sont à part, et le fichier final généré à partir du modèle. Ton modèle contient juste des insertions de variables pour que secretary puisse les trouver. Tu peux ainsi faire une boucle for sur la liste de tes équipements pour créer un tableau dans le document final. L'ODT peut être mis en gestion de version sous forme décompressée si besoin pour pouvoir faire des diff (idéalement avec un outil qui comprend l'ODT plutôt que de comparer le XML soi même). Je n'ai pas eu le temps d'aller au bout de l'approche et j'ai vu quelques petits bugs dans secretary, mais l'auteur était réactif et l'expérience intéressante.

  • # Documentation structurée

    Posté par . Évalué à 3 (+3/-1). Dernière modification le 22/01/19 à 14:54.

    C'est une problématique que l'on retrouve dans de nombreux domaine, fabrication de composants électronique, Construction navale, construction aéronautique,…

    Plusieurs spécifications existent dans ce domaine plus ou moins spécialisée par domaine industriel, par exemple pour l'aéronautique c'est la S1000D.

    Le DITA est une spécification plus généraliste et légère.

    Si tu cherche en logiciel libre, je ne connait pas de suite permettant de gérer le processus de rédaction, de construction, de versionning.

    Par contre, une boite de la région Aixoise édite une plateforme qui implémente DITE (elle s'appuie sur Alfresco) qui gère le processus complet sans trop perturber les utilisateurs (les fragments de documents sont rédigés avec Word), elle s'appelle Componize (Pour info j'ai n'ai aucun lien avec cette boite) mais leur solution est techniquement tres sexy

  • # OK c'est propriétaire ... mais

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

    Bonjour à tous et meilleurs voeux pour 2019

    J'aimerais vous parler de Confluence
    Ce produit d'atlassian est pas mal du tout même s'il souffre de quel défaut (nobody's perfect)

    C'est un éditeur HTML mais prévu pour le travail d'équipe, il intègre pas mal de choses pour stocker des pièces jointes et les afficher
    L'éditeur est très agréable tout en restant simple

    je ne fais pas la promotion de cet outil qui reste quand même propriétaire mais c'est exactement le genre de chose que j'aimerais trouver en OpenSource

    Modèles de document, gestion de l'historique, objets facilitant la vie pour afficher certaines infos comme la structure des pages par exemple, export pdf, gestion de taches, permissions etc …

    C'est fait pour faciliter la vie à une équipe de développeur + manager + marketing à découvrir

    le cout : licence perpétuelle de 10$ pour 10 utilisateurs rien à dire par contre attention le contrat de garantie fini par couter cher.

    • [^] # Re: OK c'est propriétaire ... mais

      Posté par (page perso) . Évalué à 6 (+4/-0).

      Plutôt que d'utiliser Confluence et payer des contrats exorbitants, je vous invite à acheter des évolutions fonctionnelles sur tracim. C'est un investissement sur lequel tous les utilisateurs vont capitaliser (par opposition à un coût de service) et ça peut être vraiment adapté à vos spécificités.

      Certes tracim n'offre pas le périmètre fonctionnel dz Confluence… mais dans pas mal de cas réels, c'est suffisant compte tenu de ce qui est réellement utilisé sur confluence.

      • [^] # Re: OK c'est propriétaire ... mais

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

        Confluence est venu avec JIRA et il sert de base de connaissance lié à la gestion des tickets clients JIRA Service Desk.
        C'est un bel outil mais pas trop cher et bien fait

        Tracim d'après le peu que j'ai vu (test sur 10 mn environ ) en est très proche

        Bon j'ai toujours pas trouvé l'impression ou l'export de doc et il faudrait pouvoir gérer une arborescence sur plusieurs niveaux mais je trouve l'ergonomie et le look très sympa

        C'est développez en quoi comme langage ?

        et … il manque une page wikipédia pour décrire ce bel outil

        • [^] # Re: OK c'est propriétaire ... mais

          Posté par (page perso) . Évalué à 3 (+1/-0).

          Bon j'ai toujours pas trouvé l'impression

          Ca n'existe pas, c'est une bonne idée.

          ou l'export de doc

          Si tu prends l'exemple de fichier https://demo.tracim.fr/ui/workspaces/11/contents/file/86, en haut de la prévisualisation du fichier, tu as 3 icônes cliquables (des boutons, mais ils n'en n'ont pas l'air). Actuellement ça fonctionne pour les fichiers, pas pour les documents texte édités en ligne.

          il faudrait pouvoir gérer une arborescence sur plusieurs niveaux mais je trouve l'ergonomie et le look très sympa

          Si ce que tu évoques est le fait d'organiser les contenus dans des dossiers et sous-dossiers, c'est déjà le cas. Tu as un bouton sur le tableau de bord de chaque espace partagé pour créer des dossiers. exemple : https://demo.tracim.fr/ui/workspaces/9/contents/folder/new?parent_id=null (voir https://www.tracim.fr/demo pour les login et mot de passe à utiliser)

          C'est développez en quoi comme langage ?

          Python/pyramid/hapic/sqlalchemy en backend (et base de données Postgresql/mysql éventuellement sqlite), et javascript/react/flux en frontend.

          et … il manque une page wikipédia pour décrire ce bel outil

          Exact… il faut qu'on s'en occupe :)

  • # Actes (Choix) - > Conséquences

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

    WYSIWYG : tout le monde connait mais difficile d'atteindre certains de vos objectifs
    Markup languages (nombreux choix): peu de personnes connaissent mais beaucoup plus facile d'atteindre certains de vos objectifs.

    Après plusieurs jours de recherches et de remise en question pour normaliser et simplifier notre production de documentation (Word, ODT ou txt), nous avons jeté notre dévolu sur Sphinx-documentation (basé sur restructured text) les possibilités sont nombreuses, possibilité d'utiliser des variables, des templates…bref je ne vais pas me lancer dans la description de cet outil mais ça ne coûte rien de jeter un œil.
    C'est une première étape que nous avons franchi. La seconde étape sera l'installation d'une instance ReadTheDoc (couplé à git) qui gèrerait automatiquement le versioning des documentations réalisées avec Sphinx-documentation et fournirait un référentiel de l'intégralité de nos documentations.

    En ce qui concerne la signature ou la validation il est envisageable de coupler cette solution avec un outil de GED….

    J'a bien compris que cette solution ne répond pas à votre volonté de conserver un éditeur WYSIWYG mais comme je le disais plus haut réponds à une partie des souhaits que vous avez énoncés.

    Tout est une histoire de compromis…

    Bonne soirée

  • # Calenco - DocBook XML

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

    Bonjour,

    Je suis l'ancien chef de projet documentation de Mandriva Linux, et ma société actuelle a créé un service SaaS (https://www.calenco.com) basé sur le standard Libre DocBook XML qui permet de faire tout ça, et bien plus. D'ailleurs Mageia Linux utilise toujours notre service pour produire la doc Mageia.

    N'hésitez pas à tester et revenir vers nous si besoin.

    Je serai heureux de pouvoir héberger gratuitement la documentation de projets Libres.

    Bonne journée,

    Camille.

Envoyer un commentaire

Suivre le flux des commentaires

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