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
[^] # Re: Mon grain de sel
Posté par Tsomi . En réponse au journal Documentation pour un logiciel même version que le logiciel ?. É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