Qu'en est-il de l'aversion pour la documentation dans l'industrie?

47

Il semble y avoir une aversion pour écrire même la documentation la plus élémentaire. Nos projets de lecture sont relativement nus. Il n'y a même pas de liste mise à jour des dépendances dans la documentation.

Y a-t-il quelque chose que je ne connais pas dans l'industrie qui empêche les programmeurs d'écrire de la documentation? Je peux taper des paragraphes de docs si nécessaire, alors pourquoi les autres sont-ils si opposés à cela?

Plus important encore, comment puis-je les convaincre que la rédaction de documents nous permettra de gagner du temps et d'éviter la frustration?

Rudolf Olah
la source
13
Parce que nous savons ce que nous faisons! Pourquoi devrions-nous prendre le temps de rédiger ce que nous savons déjà et que nous n'oublierons jamais!?!? Sérieusement, je travaille quotidiennement sur la même chose en travaillant sur une base de code dont le processus de conception a débuté il y a 7 ans et qui est mise à jour quotidiennement par une équipe de 4 à 7 ingénieurs. La documentation est quelque chose que nous avons toujours lutté, mais est un mal nécessaire.
Ampt
62
Parce que l'expérience a prouvé que personne ne lit la documentation.
user16764
8
D'un point de vue commercial, des tonnes de documentation coûtent de l'argent à l'entreprise ici et maintenant, alors que vous pourriez travailler sur le prochain projet pour gagner de l'argent. Ce besoin de toujours générer des profits est la pression que vous ressentez contre le "gaspillage de temps" pour la rédaction de documents. De plus, personne ne lit jamais les documents, mais plutôt les sources, car elles sont les seules autorités.
Patrick Hughes
15
Garder les documents synchronisés avec le code le plus récent peut s'avérer «difficile» si vous écrivez à un niveau supérieur à Javadoc ou à un équivalent.
Dan Pichelman
12
Ce n'est pas amusant ...

Réponses:

21

Je ne pense pas qu'il soit utile de spéculer sur les motivations des personnes qui n'adoptent pas quelque chose que vous considérez comme une bonne pratique ou qui continuent de faire quelque chose que vous considérez comme une mauvaise pratique. Dans ce secteur, les personnes qui entrent dans l’une ou l’autre de ces catégories seront bien plus nombreuses que celles que vous verrez en face-à-face, alors arrêtez de vous rendre fou.

Concentrez-vous plutôt sur le problème et les solutions possibles.

1. Écrivez vous-même une bonne documentation

Il n'est peut-être pas réaliste de s'attendre à ce que tous les membres de votre équipe concentrent leurs efforts sur les problèmes que vous considérez comme problématiques. Cela est particulièrement vrai si vous êtes un nouvel arrivant dans l’équipe. J'oserais le deviner, car si vous étiez un membre fondateur de l'équipe, il semble fort probable que vous ayez déjà résolu ce problème à un stade précoce.

Envisagez plutôt de vous efforcer de rédiger vous-même une bonne documentation et d'amener les gens à l'utiliser. Par exemple, si un membre de mon équipe me demande où se trouve le code source du projet A ou quelle configuration spéciale le projet A a besoin, je lui indique la page wiki du projet A.

Si quelqu'un me demande comment écrire une nouvelle implémentation de Factory F pour personnaliser un élément pour le client C, je leur répond que cela se trouve à la page 10 du guide du développeur.

La plupart des développeurs détestent poser des questions qui pourraient donner l'impression qu'ils ne peuvent pas simplement "lire le code" plus qu'ils ne détestent lire de la documentation. Ainsi, après suffisamment de réponses de cette nature, ils consulteront d'abord la documentation.

2. Prouvez la valeur de votre documentation

Assurez-vous de saisir chaque occasion pour indiquer où la documentation prouve sa valeur (ou l'aurait, si elle était utilisée). Essayez d’être subtile et d’éviter "Je vous l’ai dit", mais il est parfaitement légitime de dire des choses comme

Pour référence future, la page wiki de ce projet contient des informations sur la branche du code principal créée pour le support continu de la version 2.1. Ainsi, à l'avenir, nous pourrons éviter de faire un test de régression complet si les personnes qui conservent les versions publiées vérifient le wiki avant de vérifier le code.

ou

Je suis tellement heureux d'avoir écrit les étapes pour effectuer la tâche T. Cela ne me fait rien de savoir si personne d'autre ne l'utilise jamais - cela m'a déjà fait gagner plus de temps que ce que j'ai passé à l'écrire.

3. Obtenir la direction à bord

Après quelques incidents où la documentation permet d'économiser du temps et de l'argent, vous remarquerez probablement un "dégel" distinct de la documentation. C’est le moment d’appuyer sur ce point en commençant à inclure le temps de documentation dans vos estimations (même si, honnêtement, j’ai l'habitude de mettre à jour / créer des documents lorsque de longs processus sont en cours, tels que des compilations ou des archivages). Surtout s'il s'agit d'une embauche récente, il est possible que cela ne soit pas remis en question, mais plutôt considéré comme une nouvelle pratique que vous importez d'un lieu de travail précédent (ce qui pourrait bien être le cas).

Mise en garde: la plupart des patrons n'aiment pas forcer les gens à faire quoi que ce soit, en particulier ceux qui ne sont pas directement liés à une tâche facturable, alors ne vous attendez pas à ce que ce soutien prenne la forme d'un mandat. Au lieu de cela, il est plus probable que vous laissiez relativement la main libre pour écrire plus de documents.

4. Encouragez la documentation quand vous la voyez

Une des raisons pour lesquelles les gens n'écrivent pas leurs documents aussi souvent qu'ils le devraient, c'est qu'ils ont l'impression que personne ne les lit. Donc, quand vous voyez quelque chose que vous aimez, assurez-vous au moins de mentionner que vous étiez heureux que ce soit disponible.

Si votre équipe effectue des révisions de code, le moment est venu de passer à un ou deux mots subtils pour encourager les bons commentaires.

Merci de documenter la solution de contournement du bogue B dans Framework G. Je ne le savais pas et je ne pense pas que j'aurais pu comprendre ce que vous faisiez sans cela.

Si vous avez quelqu'un dans l'équipe qui est vraiment enthousiaste à propos de la documentation, cela ne fait pas de mal de la cultiver en allant déjeuner ou prendre un café et en veillant à offrir un peu de validation pour contrecarrer le découragement qu'elle peut avoir de voir le reste de l'équipe. ne valorise pas autant la documentation.

Au-delà, ce n’est vraiment pas votre problème, sauf si vous occupez un poste de direction ou de direction. Vous pouvez conduire un cheval à l'eau, mais vous ne pouvez pas le faire boire. Si ce n'est pas votre cheval, vous pourriez ne pas être heureux d'avoir soif, mais tout ce que vous pouvez faire est de remplir le bac.

Amy Blankenship
la source
1
+1 pour le point 2, répondant directement à la question du PO qui commence par "Comment puis-je convaincre ..."
Ray Toal
J'aime cette réponse, les autres se concentrent davantage sur le "pourquoi" que sur le "comment"
Rudolf Olah
@ home - c'est parce que dans la majorité des cas, rédiger une documentation ne vous fera pas gagner du temps et vous évitera de la frustration. Ils sont rarement précis et les gens ne les lisent jamais, même quand ils le sont.
Telastyn
1
Les principes SOLID ne vous font généralement pas gagner du temps et ne permettent pas non plus une meilleure conception, car la plupart des gens ne les comprennent pas complètement ou ne craignent pas vraiment. Selon votre logique, nous ne devrions pas aspirer à les appliquer, GRASP ou toute autre bonne pratique. Rappelez-moi pourquoi vous prenez la peine de participer à nouveau aux programmeurs?
Amy Blankenship
Il est très utile de spéculer sur les motivations des personnes.
tymtam
55

Mon expérience comporte deux facteurs principaux:

Les délais

La plupart des entreprises sont tellement motivées par la date que le contrôle qualité, la dette technique et la conception réelle sont coupés, afin que le chef de projet ne soit pas mal vu ou ne respecte pas les délais absurdes et promis de ses clients. Dans cet environnement où même la qualité fonctionnelle est réduite, un investissement à long terme tel que la documentation a peu de chance.

Changement

Une pratique relativement nouvelle pour les développeurs consiste à minimiser les commentaires. L'idée est que le fait de garder les informations à deux endroits (le code [y compris les tests] et les commentaires autour du code) génère beaucoup de travail en les maintenant synchronisées sans grand bénéfice. "Si votre code est si difficile à lire que vous avez besoin de commentaires, ne serait-il pas mieux de passer du temps à le nettoyer?"

Personnellement, je ne regarderai même plus les commentaires. Le code ne peut pas mentir.

La documentation suit la même veine. Avec l'adoption généralisée de l'agilité, les utilisateurs reconnaissent que les exigences changent régulièrement. Avec le recours généralisé à la refactorisation, l'organisation du code changera considérablement. Pourquoi passer du temps à documenter tout ce qui va changer? Le code et les tests devraient faire assez bien.

Telastyn
la source
11
+1 pour "personnellement, je ne regarderai même plus les commentaires", je pense que c'est courant; lorsque vous atteignez un certain niveau de confort avec le code lui-même, vous pouvez le lire plus rapidement que les commentaires (et encore plus rapidement si les commentaires ne vous gênent pas) et si le code ne ment pas
Jimmy Hoffa
41
Cela manque l’intérêt des commentaires, c’est d’expliquer pourquoi . Ils n'ont pas besoin d'être partout et ils n'ont pas besoin d'être très longs, mais un lien bien placé vers les règles de gestion décrivant pourquoi les 20 prochaines lignes de logique vraiment bizarre existent dans son état actuel est bien plus pratique que d'essayer de parcourir l'historique des versions pour trouver le raisonnement d'origine.
zzzzBov
7
@zzzzBov - absolument, c'est la vision moderne des choses. Cela a changé par rapport aux points de vue précédents qui encourageaient les commentaires plus omniprésents. De même, la documentation de ce que fait le code a été réduite à une documentation qui explique pourquoi il le fait (docs de conception par exemple).
Telastyn
8
Le code peut mentir. Le client a peut-être eu envie de quelque chose et le code lui a été attribué pour faire autre chose. Donc, si tout ce que vous avez maintenant est le code, c'est bien?
Jeudi
6
Le code peut mentir ... J'ai une méthode de 4 000 lignes (hé, je ne l'ai pas créé, je le possède juste maintenant ...) et je vois une collection clairement nommée "productList", alors pour un nouveau changement, j'ajoute un produit. objecter à cela. Génial. Seulement cela ne fonctionne pas, il s'avère que certains développeurs précédents étaient "efficaces" et réutilisaient la variable de type List afin d'éviter d'encombrer les 4 000 lignes avec trop de variables, et dans cette portée, elle contient des objets Client ...
Kevin Rubin
17

Il y a un certain nombre de facteurs en jeu ici:

  1. Le code bien écrit est sa propre documentation. Toutes choses étant égales par ailleurs, il est préférable d'écrire un code plus clair qui parle pour lui-même plutôt que davantage de documentation. Faites cela, et vous devrez modifier moins de documentation lorsque vous modifierez ce code.

  2. Écrire de la documentation est sans doute une compétence différente de celle d’écrire du code. Certains développeurs de logiciels y réussissent mieux que d’autres. Certains sont bien meilleurs pour écrire du code que pour écrire de la documentation.

  3. La documentation ne doit être écrite qu'une fois , pas deux fois (une fois dans le code source et une autre fois dans le guide du programmeur). C'est pourquoi nous avons des choses comme les commentaires XML et les générateurs de documentation. Malheureusement, l'utilisation de tels outils peut s'avérer plus délicate et fastidieuse que la rédaction manuelle de la documentation. C'est pourquoi vous ne voyez pas ces outils largement utilisés.

  4. Une bonne documentation prend du temps et est difficile à bien faire. Toutes choses étant égales par ailleurs, l'écriture de nouveau code peut avoir plus de valeur que la rédaction de documentation pour du code déjà existant.

  5. Lorsque le code change, vous devez également modifier la documentation. Moins il y a de documentation, moins il faut en changer.

  6. De toute façon, personne ne lit la documentation, alors pourquoi s'en préoccuper?

Robert Harvey
la source
2
re # 1, je ne pense pas que ce soit jamais le cas, mais le n ° 4 est certainement vrai
Rudolf Olah
3
@whatsisname: Pas du tout. Rédigez un code plus clair nécessitant moins de documentation. Vous devrez modifier moins de documentation lorsque vous modifierez ce code.
Robert Harvey
2
@thursdaysgeek: Ces puces signifient que vous ne devriez pas avoir à écrire deux fois la documentation: une fois pour les commentaires de code et une autre fois pour la référence du fichier d'aide / du programmeur. Vous ne devriez certainement pas avoir à le réécrire deux fois. Est-ce que vous lisez ce truc?
Robert Harvey
4
# 6 ... Je pense que c'est une idée fausse commune. Un grand nombre de gens lisent la documentation à fond.
Dynamic
3
@tymek: Vous avez votre signe à l'envers. Mes amis, ce n'est pas un tutoriel sur la création de documentation. c'est un calcul qui explique pourquoi les développeurs ont une attitude négative à son égard.
Robert Harvey
11

Éléphant dans la salle: les programmeurs ne sont pas (nécessairement) des écrivains. Ils ne sont pas non plus nécessairement disposés à étoffer leurs implémentations aux rédacteurs techniques. Deuxième éléphant dans la salle: les rédacteurs techniques ne sont généralement pas en mesure d’étoffer les détails utiles aux futurs développeurs (même si les développeurs daignent les leur expliquer).

Un système complexe peut devenir presque impénétrable avec le temps sans documentation appropriée. Le code perd moins de valeur inversement proportionnellement à son pouvoir de vérification [sic]. Résolu, la direction recrute un ingénieur logiciel capable de lire le code et de convaincre les développeurs, de le payer à un tarif préférentiel et de l’obliger à documenter et à maintenir la documentation. Cet auteur peut lire le code et saura quelles questions poser et complétera les détails si nécessaire. Tout comme vous avez un service d'assurance qualité, vous avez un service de documentation interne.

Le code deviendra plus précieux, car vous pouvez le céder sous licence à une tierce partie (car il peut le comprendre), le code peut être plus facilement audité et amélioré / re-factorisé, vous aurez une meilleure réutilisation du code même là où vous pouvez facilement Envisagez des versions plus légères de votre logiciel, et vous serez en mesure d'introduire plus facilement de nouveaux développeurs dans le projet. Vos ingénieurs de support aimeront travailler pour vous.

Cela n'arrivera jamais.

naftalimich
la source
1
Sans oublier que, lorsque l'on essaie de décrire le code existant, il devient plus difficile de donner une bonne description lorsque le code et les fonctionnalités sont si complexes que personne ne sait ce qu'il fait déjà. Par conséquent, toute nouvelle modification a un impact que le nouveau développeur n'a pas fait. savoir sur ...
Kevin Rubin
1
Je suggérerais que "la capacité de base de communiquer ses intentions avec de la documentation (limitée)" est une compétence nécessaire du programmeur. Un programmeur ne doit pas nécessairement être un poète, mais s'il ne peut pas documenter, honnêtement, je ne le veux pas dans mon équipe. Une telle personne est une responsabilité à long terme.
5

Plus important encore, comment puis-je les convaincre que la rédaction de documents nous permettra de gagner du temps et d'éviter la frustration?

Est-ce qu'il fait ça?

Il existe deux types de documentation:

Documentation utile

Explique comment utiliser un produit fini, une API, les adresses IP ou les noms d'URL de nos serveurs, etc. En gros, tout ce qui est utilisé lourdement et quotidiennement. Les mauvaises informations seront rapidement détectées et corrigées. Doit être trouvé facile et facile à modifier (par exemple, un wiki en ligne).

Documentation inutile

Une documentation qui change souvent, très peu de gens s’y intéressent et personne ne sait où la trouver. Comme l'état actuel d'une fonctionnalité implémentée. Ou des documents d'exigence dans un document Word caché quelque part dans SVN, mis à jour il y a 3 ans. Il faudra du temps pour écrire cette documentation, et pour découvrir qu’elle est fausse ultérieurement. Vous ne pouvez pas compter sur ce type de documentation. C'est inutile. Cela fait perdre du temps.

Les programmeurs n'aiment pas écrire ou lire une documentation inutile. Mais si vous pouvez leur montrer une documentation utile, ils l'écriront. Lors de mon dernier projet, nous avons eu beaucoup de succès avec l’introduction d’un wiki où nous pourrions écrire toutes les informations dont nous avons souvent besoin.

Uooo
la source
4

Je dirais que la raison principale est un manque de volonté et un manque de compréhension de la fonction de la documentation. Il existe un certain nombre de classes de documentation à prendre en compte:

Documentation produit / version

C'est tout ce qui sort avec votre produit "fini". C’est plus que des manuels, c’est des fichiers README, des journaux de modifications, des guides pratiques, etc. En théorie, vous pouvez vous en tirer, ne pas les écrire, mais vous vous retrouvez avec un produit que les gens ne veulent pas utiliser ou un fardeau de support inutilement coûteux.

Documentation API

Ceci décrit quelque chose qui devrait être relativement statique. Étant donné que de nombreux consommateurs peuvent coder votre API, celle-ci doit être suffisamment stable pour que la prose décrivant son utilisation ait de la valeur. Décrire quels paramètres sont pris en charge, quelle valeur de retour peut être et quelles erreurs peuvent être générées, permettra aux autres utilisateurs de comprendre votre API au bon niveau d'abstraction - l'interface (et non l'implémentation).

Commentaires de code

L’opinion de l’industrie sur les commentaires semble évoluer pour le moment. Lorsque j'ai commencé à coder de manière professionnelle, les commentaires étaient une condition sine qua non pour écrire du code. Maintenant, la mode est d’écrire du code si clair que les commentaires sont inutiles. J'imagine que c'est en partie dû au fait que beaucoup de langages modernes sont écrits à un niveau beaucoup plus élevé et qu'il est beaucoup plus facile d'écrire du code lisible en Java, JavaScript, Ruby, etc. que ce n'était le cas en assembleur. , C, FORTRAN, etc. Ainsi, les commentaires ont beaucoup plus de valeur.

Je crois toujours que les commentaires décrivant l’ intention d’une section de code ou les raisons pour lesquelles un algorithme a été choisi plus évident (afin d’éviter les réflexes trop zélés de refactorisation du fait de «réparer» du code qui ne le fait pas) sont utiles. t réellement besoin d'être corrigé).

Malheureusement, la décision des programmeurs de ne pas documenter est très égoïste, rationalisée et généralisée. La réalité est que, à l'instar du code, le principal public visé par la documentation est les autres personnes. Ainsi, la décision d'écrire (ou de ne pas écrire) de la documentation, à n'importe quel niveau, doit être prise au niveau de l'équipe. Pour les niveaux d'abstraction plus élevés, il peut être plus logique de faire appel à une personne autre que les développeurs. En ce qui concerne la documentation au niveau des commentaires, il convient de s’accorder sur l’objectif et l’intention des commentaires, en particulier au sein d’équipes expérimentées et expérimentées. Il ne sert à rien que des développeurs seniors écrivent du code que les développeurs juniors ne peuvent pas aborder. Une documentation bien placée et bien écrite peut permettre à une équipe de fonctionner beaucoup plus efficacement

Dancrumb
la source
1
+1 pour "le public cible principal de la documentation est d'autres personnes". Trop de programmeurs n'apprécient pas vraiment la communication avec les autres. (C'est aussi pourquoi ils auront du mal à avancer dans l'ancienneté.)
Donal Fellows
4

Voici mes deux cents.

  1. Le Manifeste Agile indique "Un logiciel fonctionnant avec une documentation complète" et tout le monde ne lit pas pour atteindre "C'est-à-dire que même si les éléments de droite ont de la valeur, nous valorisons davantage les éléments de gauche."

  2. Malheureusement, il est fréquent de lire https://en.wikipedia.org/wiki/Code_and_fix et la documentation ne fonctionne pas avec ce modèle (la synchronisation n'est pas assurée).

  3. L'industrie du développement de logiciels n'est pas bien réglementée. Il n'y a aucune obligation légale d'écrire de la documentation.

  4. Le code auto-documenté est la tendance actuelle.

Cela dit, je pense qu’il existe de nombreux documents de qualité.

tymtam
la source
(1) " Nous attachons plus d'importance aux choses de gauche ... " n'implique pas que nous ne nous soucions absolument pas du côté droit. (2) " 4. Le code auto-documenté est la tendance actuelle " Si la documentation n'est pas nécessaire, pourquoi se fait-il alors que les gens se plaignent avant tout d'une documentation erronée ou manquante? (3) Chaque développeur qui a besoin d'informations perd le temps qu'il passe à ne pas documenter son travail , car il doit numériser 5 000 lignes de code auto-documenté au lieu de 5 pages de documentation. L'efficacité, c'est autre chose, mais bon, nous sommes agiles!
JensG
2

La documentation prend du temps et je soupçonne que de nombreux développeurs ont eu trop de problèmes avec une documentation pire qu'inutile. Ils ont l’idée que non seulement la documentation leur causera des ennuis de la part de leur responsable (le même type qui continue de couper le volet AQ de l’horaire), mais que cela n’aidera personne, pas même eux.

Toute documentation à peu près décente est un investissement dans l’avenir. Si vous ne vous souciez pas de l'avenir (parce que vous ne pensez pas au-delà du prochain chèque de paie ou parce que vous pensez que ce ne sera pas votre problème), alors l'idée de faire de la documentation est extrêmement pénible.

Michael Kohne
la source
2

De nombreuses autres réponses occultent le fait qu'il existe au moins deux types de documentation: une série pour les autres développeurs et une série différente pour les utilisateurs finaux. Selon votre environnement, vous aurez peut-être également besoin de documentation supplémentaire pour les administrateurs système, les installateurs et le personnel du support technique. Chaque public cible a des besoins et des niveaux de compréhension différents.

Considérons le développeur (stéréo-) typique: Il est un codeur par choix. Il a choisi une carrière hors du regard du public et passe de longues heures derrière un clavier à communiquer principalement avec lui-même. Le processus de documentation est une forme de communication et les compétences requises pour produire une bonne documentation vont à l'encontre des compétences requises pour produire un bon code.

Un bon rédacteur de documentation peut communiquer dans plusieurs langues: la langue des utilisateurs, la langue de la direction, la langue du personnel de support, la langue des développeurs. C'est un travail de rédacteur de documentation de comprendre ce qu'un codeur communique et de le traduire en une forme que tous les autres groupes peuvent comprendre.

Lorsque vous attendez des programmeurs qu'ils développent les compétences nécessaires pour devenir de bons communicateurs (écrits ou autres), le temps passé à perfectionner l'ensemble des compétences principales (codage!) Est réduit. Plus il s'éloigne de sa zone de confort (codage et communication avec d'autres codeurs), plus il lui faudra du temps et de l'énergie pour mener à bien cette tâche. Vous pouvez raisonnablement vous attendre à ce qu'un codeur professionnel veuille se concentrer principalement sur ses compétences essentielles, au détriment de toutes les autres.

Pour cette raison, il est préférable de laisser la documentation (à l'exception des codeurs) (à l'exception des commentaires de code intégrés).

George Cummins
la source
4
Oh, pisse. Plus vous apprenez à bien faire, plus vous apprenez à bien faire les choses. Tout comme les personnes qui connaissent plusieurs langues programment mieux que celles qui n'en connaissent qu'une (car elles connaissent plus de façons de penser au problème), être capable d'écrire et même de visualiser graphiquement vous donne plus d'outils pour penser et résoudre des problèmes. Les compétences dont vous avez besoin pour décrire ce qui se passe sont les mêmes que celles dont vous avez besoin pour déterminer ce qui devrait se passer.
Amy Blankenship
1
Je veux que les autres développeurs soient ou deviennent des communicateurs compétents. La grande majorité de la programmation que nous réalisons (du moins dans les logiciels d’entreprise) n’exige pas l’ensemble des compétences de codage les plus perfectionnées. Cela nécessite de meilleures compétences de communication de personne à personne afin que les futurs développeurs comprennent ce qui a été écrit. Plus un développeur peut communiquer efficacement, en particulier avec des personnes qu'il ne rencontrera jamais, mieux il sera pensé à long terme, et probablement pas pour un code intelligent.
Kevin Rubin
2

La lecture du code vous montre comment cela fonctionne. Il ne peut pas expliquer pourquoi : vous avez besoin de commentaires.

La lecture du code vous indique le nom d'une méthode et les types de paramètres. Il ne peut pas expliquer la sémantique, ni l'intention exacte de l'auteur: vous avez besoin de commentaires.

Les commentaires ne remplacent pas la lecture du code, ils y ajoutent.

Benlast
la source
4
+1 pour le sentiment. Mais ce n'est pas une réponse à la question; vous semblez répondre à autre chose que la question posée.
Bignose
2

La documentation n'est pas exécutée en tant que code. En conséquence, il n’ya souvent pas de boucles de rétroaction efficaces pour vérifier que la documentation est en place et complète. C'est la même raison pour laquelle les commentaires de code ont tendance à pourrir.

Donald Knuth a fait la promotion de Literate Programming comme moyen d’améliorer la qualité des logiciels et d’écrire efficacement la documentation avec le code. J'ai vu quelques projets qui ont utilisé cette approche assez efficacement.

Personnellement, j'essaie de rester fidèle à la tendance moderne consistant à maintenir l'API publique de votre code aussi lisible que possible et d'utiliser des tests unitaires pour documenter l'utilisation par d'autres développeurs. Je pense que cela fait partie de l'idée plus large d'avoir votre API sous une forme qui peut être explorée et découverte. Je pense que cette approche fait partie de ce que HATEOAS essaie de réaliser avec les services Web.

aboy021
la source
Afin de justifier mes choix en matière de génération automatisée de documentation, j'ai mis au point une formule simulée pour montrer que l'inertie humaine est la cause de tous les commentaires. Tout en développant l'argumentation, j'ai constaté que la création de méthodes procurant des avantages réels aux développeurs, telles que la génération partiellement automatisée de diagrammes à partir de méta-commentaires dans le code source, tend à être mise à jour chaque fois qu'un développeur essaie de comprendre le code. BTW, le plus souvent ce développeur est juste "future me".
Wolfmanx
0

Un point mineur, mais qui semble être important pour certains développeurs qui écrivent de manière odieusement peu de documentation: ils ne peuvent pas taper. Si vous avez une idée approximative du système à 10 doigts, vous avez tendance à écrire davantage de documentation simplement parce que c'est facile. Mais si vous êtes coincé à chasser et à picorer, vous êtes perdu. Si je suis responsable de l'embauche, c'est quelque chose que je vérifierais.

Hans-Peter Störr
la source
0

Les personnes qui n'aiment pas lire la documentation n'aiment pas écrire de la documentation. Beaucoup de programmeurs feront tout leur possible pour éviter de lire un document attentivement.

Ne vous concentrez pas sur l'écriture, concentrez-vous sur la lecture. Lorsque les programmeurs lisent de la documentation et en assimilent des éléments, ils en voient la valeur et sont beaucoup plus enclins à en écrire.

Joeri Sebrechts
la source
-1

Lorsque j'ai commencé mon travail actuel et repris un projet matériel + logiciel des personnes qui travaillaient auparavant sur ce projet, on m'a remis une centaine de documents Word décrivant le système. Il a fallu des jours pour produire. Je l'ai regardé peut-être deux fois. Malgré la quantité massive d'informations contenues dans ce document, il répondait rarement aux questions que j'avais sur le système, et même lorsqu'il le faisait, il était plus rapide d'examiner le code.

Après assez d'expériences comme ça, vous commencez juste à penser, pourquoi s'embêter? Pourquoi passer votre temps à répondre à des questions que personne n’a jamais posées? Vous commencez à réaliser à quel point il est vraiment difficile de prévoir les informations que les utilisateurs rechercheront dans la documentation; il est inévitablement rempli de faits qui s'avèrent inutiles, peu clairs ou évidents, et qui manquent de réponses aux questions les plus pressantes. N'oubliez pas que produire une documentation utile est un effort de prédiction du comportement humain. Tout comme une interface utilisateur a peu de chances de réussir avant d’avoir répété plusieurs fois les tests et le débogage, il est naïf de penser qu’il est possible d’écrire une documentation utile basée uniquement sur les attentes des utilisateurs en matière d’interprétation du système. rôle que la documentation et son langage joueront dans cette interprétation.

J'ai tendance à penser que l'essentiel de la pression pour écrire de la documentation provient du fait que c'est une corvée désagréable et que des gens se culpabilisent de faire des corvées désagréables ("Vous n'avez pas mangé votre studboide!").

POURTANT

Je ne pense pas que la documentation soit, à tous égards, sans espoir. Je pense que c'est surtout sans espoir lorsque les gens considèrent la documentation comme un fardeau supplémentaire à remplir avant qu'un travail ne soit terminé, comme un dernier travail de nettoyage à effectuer et une case à cocher. La documentation est quelque chose que vous devriez intégrer aux aspects de votre journée que vous faites toujours de toute façon. Je pense que le courrier électronique est un excellent moyen de faire de la documentation. Lorsque vous ajoutez une nouvelle fonctionnalité, écrivez rapidement à quelques personnes un message expliquant en quoi il consiste. Lorsque vous dessinez un nouveau schéma, générez un fichier PDF et envoyez-le à toute personne susceptible d’être intéressée. Les avantages de l'email sont:

  1. Les gens consultent généralement leurs courriels, alors que personne ne se faufile dans un dossier appelé "doc".

  2. Le courrier électronique existe dans son contexte, entouré d'autres courriels traitant de la fonctionnalité et des fonctionnalités associées, ainsi que de tout ce qui se passait à l'époque.

  3. L'email est court et concentré et a une ligne d'objet.

  4. Le courrier électronique permet aux personnes intéressées de poser des questions immédiatement.

  5. Le courrier électronique est extrêmement consultable, car les gens l'utilisent pour tout et les clients de messagerie ont beaucoup progressé au fil des ans.

  6. Si c'est dans un email, au moins une autre personne sait où le trouver.

En théorie, il devrait sembler que les commentaires dans le code devraient également être "des aspects de votre journée que vous faites toujours de toute façon", mais pour être honnête, je ne lis jamais de commentaires dans le code. Je ne sais pas pourquoi, mais ils ne sont tout simplement pas très utiles, peut-être parce qu'il y a un manque de contexte, ce que le courrier électronique résout.

Owen
la source
À l'exception de # 4 ("les personnes qui se soucient de poser des questions tout de suite"), aucun des avantages de messagerie que vous avez énumérés n'a fonctionné de manière fiable pour moi. 1: Les gens ont tendance à ne pas tenir compte email, quand il y a beaucoup de celui - ci 2: Email tend souvent au contexte lose, l' enterrant dans les questions secondaires et overquoting 3: Les e - mails sont trop souvent long / large et ont tendance à perdre le focus que la discussion entre dans de plus en plus de problèmes secondaires et de sujets sont souvent sans objet / obsolètes ("Re: WTF est arrivé sur le serveur aujourd'hui?") ...
gnat
... 5: La recherche par courrier électronique est fortement compromise par la possibilité de supprimer des courriers. Cette fonctionnalité est utilisée par tous les utilisateurs de messagerie actifs et les utilisateurs de messagerie actifs. Elle utilise beaucoup 6: voir 5, si le courrier est supprimé, personne ne pourra le trouver (la seule chose sur laquelle je peux compter est de rechercher mes mails envoyés et c'est uniquement parce que j'essaie très fort de ne pas les supprimer). Autre que les éloges par courrier électronique (ce qui me semble tout à fait injustifié), vous soulignez quelques points
positifs
@gnat Je suppose que cela peut varier d'une entreprise à l'autre à propos de la suppression. Dans mon entreprise, nous sauvegardons tous les courriels, ainsi que les archives de tous les courriels d'anciens employés. Chaque fois qu'une nouvelle personne commence une tâche, nous lui transmettons tous les courriels connexes. Je suppose une différence de style.
Owen
Oui, cela dépend beaucoup du style / de la culture. Bien que "lutter contre la suppression" soit certainement faisable (et même techniquement simple à réaliser en exportant des fils de courrier vers un serveur), des choses comme les garder concentrés, les sujets pertinents, citer des limites limitées à des limites raisonnables est une chose très culturelle, nécessitant beaucoup d'effort et détermination (et soutien de la direction) à maintenir ... Par rapport à cet effort, et particulièrement au besoin d’achat de la part de la direction, maintenir des éléments comme les dossiers wiki / code comments / doc peut s’avérer plus facile
gnat