Journal Documentation pour un logiciel même version que le logiciel ?

Posté par  . Licence CC By‑SA.
Étiquettes : aucune
8
23
mar.
2018

Je me pose une question existentielle !

Quand on développe un programme et qu'on rédige sa documentation, la documentation doit elle avoir le même numéro de version que le programme ou la documentation doit avoir son propre numéro de version par rapport au programme ?

Vous avez 4 heures :).

  • # Non

    Posté par  . Évalué à 10.

    Mettre à jour la doc et le logiciel sont deux choses totallement indépendantes. Tu peux livrer une nouvelle version du logiciel qui corrige des bugs et qui n'appelle pas de modification de doc, tout comme tu peux corriger ou améliorer ta doc, sans forcément devoir sortir un nouveau logiciel.

    En théorie, la théorie et la pratique c'est pareil. En pratique c'est pas vrai.

    • [^] # Re: Non

      Posté par  . Évalué à 4.

      Une autre question vaut t’il mieux avoir une documentation dans le même dépôt git que le programme ou dans un dépôt séparer ?

      • [^] # Re: Non

        Posté par  . Évalué à 9.

        Là par contre je pense que c'est moins important. Encore une fois c'est le flot de travail qui va diriger la réponse. Je dirais que si c'est une équipe séparée (rédacteur + traducteurs) ça a du sens de faire un git séparé, mais si c'est une mini équipe (qques devs qui au passage font la doc), tu peux la mettre au même endroit.

        En théorie, la théorie et la pratique c'est pareil. En pratique c'est pas vrai.

  • # Ce qui importe

    Posté par  . Évalué à 10.

    Ce qui importe est de savoir à quelle version du soft la doc correspond.

    Typiquement t'aurais un build system qui génere le soft et la doc en même temps. Si ca se trouve tu n'as pas besoin de changer la doc, et le système de build se charge de génèrer la doc avec le nouveau numéro de version.

    • [^] # Re: Ce qui importe

      Posté par  . Évalué à 3.

      Ouai mais la doc et le logiciel peuvent évoluer séparément.
      Alors puisque t'es là je vais demander exiger (on vit à une époque où tout M'est dû à Moi après tout):
      Comment est gérée la doc chez MS?

      -Y'a-t-il un système séparé qui gère les documentations? Je suppose que oui, ça fait partie des procédures de qualité.
      -Du coup, si tu fais un build qui ne change pas la doc, est-ce que le document QA est mis à jour? Au moins, il doit y avoir une mention du nouveau build et de l'applicabilité de la doc au build?
      -Si tu mets la doc à jour sans changer le reste du logiciel, tu n'as pas forcément besoin d'un nouveau build, mais en même temps, si tu comptes sur le build pour générer la doc, tu as 2 procédures séparées pour la générer?
      -Ou alors on décide que quel que soit le changement, on refait un build, et on relâche une nouvelle version du logiciel et de la doc. C'est peut-être plus simple pour gérer les versions, mais sans doute pas pour les certifications.

      Merci d'avance!

      • [^] # Re: Ce qui importe

        Posté par  . Évalué à 2.

        Ouai mais la doc et le logiciel peuvent évoluer séparément.

        Ben oui, et dans le système de build c'est géré, seule a doc aura un rebuild tant que rien ne change dans le soft. Tu peux tout à fait avoir une version de doc en supplément, mais la doc doit absolument inclure la version du soft qu'elle référence aussi.

        Comment est gérée la doc chez MS?

        C'est très différent parce qu'ils ont des besoins très spéciaux et une organisation entière chargée de la doc. C'est quelque chose que 99% des gens n'ont pas les moyens (ni les besoins), donc je dirais que c'est probablement pas un bon exemple à prendre.

  • # point de vue utilisateur

    Posté par  (site Web personnel) . Évalué à 10.

    La doc, c'est fait pour l'utilisateur, et lui, il a besoin de savoir quelle doc lire.
    Pas forcément la dernière, s'il utilise un paquet fourni par sa distribution.
    Donc, une doc par version, c'est pas mal.

  • # Mon grain de sel

    Posté par  (site Web personnel) . Évalué à 2.

    Idéalement, j'aimerai bien avoir ça côté versionning :

    • la doc et le logiciel sont versionné séparément (je ne parle pas de gestion de version via git ou autre)
    • chaque version de la doc est associée à un ensemble de version du logiciel
    • quand tu mets à jour la doc (correction, clarification, etc…), tu bump sa version, pas de soucis
    • quand tu mets à jour le logiciel, et que cela n'impacte pas la doc, en réalité si, ça l'impacte : l'ensemble de version compatible est modifié

    En gros, dès que tu modifie le logiciel, la doc s'en retrouve impactée, dans tout les cas.

    Et du coup côté procédure :

    • une seule procédure pour générer la doc, qui est déclenchée par un build (en général déclenché par une git hook en même tant que l'intégration continue, voir le déploiement continu)
    • la doc et le logiciel dans le même dépôt, ou alors un git-submodule pour ne pas perturber les rédacteurs/traducteurs, une mise à jour de la doc implique un nouveau trigger de la git hook

    Mais en réalité ce que je fais vraiment c'est plutôt :

    • j'ai la doc dans le même dépôt que mon logiciel
    • doc d'API générée par les docstrings de mon code, et 2-3 tutos que je mets à jour à chaque version majeure si besoin
    • ma doc et mon logiciel ont le même numéro de version (l'utilisateur à pas à se casser la tête, logiciel version X.Y.Z, doc version X.Y.Z)

    https://link-society.com - https://kubirds.com

    • [^] # Re: Mon grain de sel

      Posté par  . Évalué à 1. Dernière modification le 29/03/18 à 19:53.

      Je suis d'accord avec à peu près tout en théorie, sauf l'histoire de doc générée par les docstrings et 2 ou 3 tutos. Il ne faut pas que de la doc développeur, il faut aussi (et principalement) de la vraie bonne doc utilisateur (2 ou 3 tutos, ça n'en est pas). Ça, j'en paie assez le prix au quotidien.

      J'aime notamment la philosophie chez OpenBSD : tu peux proposer la fonctionnalité que tu veux, tant que tu n'as pas livré une doc utilisateur simple, carrée, correcte, maintenue et maintenable, eh bien tu peux te le garder ton patch, il ne sera pas intégré. La doc et le code forment un tout indissociable.

      Si les développeurs n'arrivent pas à écrire une doc utilisateur simple, c'est que ça en dit long sur le reste. Pour moi, la doc doit aussi être vue comme un important contrôle qualité du code. La doc utilisateur alambiquée ou manquante trahit le mauvais code et les usines à gaz.

      GRUB3 will be Elisp serialized as XML jited to JVM running as Eclipse plugin on a Mac running in a virtual PC in a Xen instance on a 286er.

  • # Oui

    Posté par  (site Web personnel) . Évalué à 7.

    la documentation doit elle avoir le même numéro de version que le programme

    Oui, tout simplement parce que c’est plus simple pour l’utilisateur, pour savoir à quelle doc se référer.

    J’en vois venir avec des « mais la doc peut évoluer sans que le logiciel n’évolue, donc le numéro de la doc va changer mais pas le logiciel ». Ben perso si ma doc doit évoluer drastiquement mais que rien de neuf n’est apparu pour le logiciel, ben je vais quand même sortir une nouvelle version du tout. Surtout que la doc est livrée avec le logiciel (dans une page man, ou en .rst dans les sources), en plus d’être dispo sur un site web.

  • # Révision indépendante

    Posté par  (site Web personnel) . Évalué à 3.

    Cela me semble logique que la documentation ait le même numéro de version que le code, et on peut (doit ?) rajouter un numéro supplémentaire pour la révision de la documentation en elle-même.

    C’est ce qui est utilisé pour gérer les paquets deb :
    1.2.3-4 avec 1.2.3 la version du logiciel et 4 la révision de la documentation.

  • # Oui

    Posté par  (site Web personnel) . Évalué à 4. Dernière modification le 26/03/18 à 10:02.

    Oui, pour moi c'est très important.

    J'ai été confronté à ce problème quand j'ai développé irccd. Au début j'avais commencé à écrire la documentation sous forme de wiki, exactement comme löve. Seul problème c'est que lorsque tu souhaites rajouter/enlever des fonctionnalités, tu commences à avoir un bordel monstre. Par exemple ce module comporte des fonctions présentes plus tard et d'autres supprimées. Ça devient compliqué pour l'utilisateur…

    Autre point, si tu suis le semantic versioning correctement, et souhaites maintenir deux versions de ton logiciel (par exemple 4.5, 5.1) tu vas devoir fournir les deux documentations le temps que les gens migrent de la 4 à la 5.

    Le plus simple, est de livrer ta documentation avec ton application, ou d'en faire plusieurs pages sur ton site. En tout cas, je déconseille fortement les wikis.

    Pour ta deuxième question, j'ai tendance à préférer la documentation dans le même dépôt. Ça facilite le travail et la maintenance.

    l'azerty est aux dispositions ce que subversion est aux SCMs

Suivre le flux des commentaires

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