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 gUI (Mastodon) . É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 gusterhack . É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 gUI (Mastodon) . É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 pasBill pasGates . É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 Maclag . Évalué à 3.
Ouai mais la doc et le logiciel peuvent évoluer séparément.
Alors puisque t'es là je vais
demanderexiger (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 pasBill pasGates . Évalué à 2.
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.
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 eric gerbier (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 David Delassus (site web personnel) . Évalué à 2.
Idéalement, j'aimerai bien avoir ça côté versionning :
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 :
Mais en réalité ce que je fais vraiment c'est plutôt :
https://link-society.com - https://kubirds.com
[^] # Re: Mon grain de sel
Posté par Tsomi . Évalué à 1. Dernière modification le 29 mars 2018 à 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.
a systems programmer has seen the terrors of the world and understood the intrinsic horror of existence
# Oui
Posté par louiz’ (site web personnel) . Évalué à 7.
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 mzf (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-4avec1.2.3la version du logiciel et4la révision de la documentation.# Oui
Posté par David Demelier (site web personnel) . Évalué à 4. Dernière modification le 26 mars 2018 à 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.
git is great because linus did it, mercurial is better because he didn't
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.