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

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?

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.

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.

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?

É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.

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.

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

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é.

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.

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).

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.

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.

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.

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.

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.