Quelle est l'aversion pour la documentation dans l'industrie?
Il semble y avoir une aversion à écrire même la documentation la plus élémentaire. Les README de nos projets sont relativement nus. Il n'y a même pas de listes de dépendances mises à jour dans les documents.
Y a-t-il quelque chose que je ne connais pas dans l'industrie qui fait que les programmeurs n'aiment pas écrire de la documentation? Je peux taper des paragraphes de documents si nécessaire, alors pourquoi les autres y sont-ils si opposés?
Plus important encore, comment puis-je les convaincre que la rédaction de documents nous fera gagner du temps et de la frustration à l'avenir?
Je ne pense pas qu'il soit utile de spéculer sur les motivations des personnes qui n'adoptent pas quelque chose que vous pensez être une bonne pratique ou qui continuent de faire quelque chose que vous voyez comme une mauvaise pratique. Dans cette entreprise, les personnes qui appartiennent à l'une de ces catégories ou aux deux seront de loin plus nombreuses que celles avec qui vous serez d'accord, alors arrête de te rendre fou.
Concentrez-vous plutôt sur le problème et les solutions possibles.
1. Ecrivez 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 dirigent leurs efforts vers les problèmes que vous voyez. Cela est particulièrement vrai si vous êtes un nouveau venu dans l'équipe. J'oserais deviner que vous l'êtes, car si vous étiez un membre fondateur de l'équipe, il semble très probable que vous auriez déjà résolu ce problème dès le début.
Pensez plutôt à travailler vers l'objectif d'écrire 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 de quelle configuration spéciale le projet A a besoin, je le dirige vers la page wiki du projet A.
Si quelqu'un me demande comment écrire une nouvelle implémentation de Factory F pour personnaliser quelque chose pour le client C, je lui dis que c'est à la page 10 du guide du développeur.
La plupart des développeurs détestent poser des questions qui pourraient leur faire croire qu'ils ne peuvent pas simplement "lire le code" encore plus qu'ils détestent lire la documentation, donc après suffisamment de réponses de cette nature, ils iront d'abord dans la documentation.
2. Prouvez la valeur de votre documentation
Assurez-vous de saisir chaque occasion pour indiquer où la documentation prouve sa valeur (ou aurait, si elle était utilisée). Essayez d'être subtil et évitez "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 de base qui a été créée pour la prise en charge continue de la version 2.1, donc à l'avenir nous pouvons éviter d'avoir à faire un test de régression complet si les personnes qui maintiennent les versions publiées vérifient le wiki avant de vérifier le code.
ou
Je suis tellement content d'avoir noté les étapes de réalisation de la tâche T. Je me fiche 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.
. Obtenez la gestion à bord
Après quelques incidents où la documentation permet de gagner du temps et de l'argent, vous remarquerez probablement un "dégel" distinct vers la documentation. C'est le moment d'appuyer sur le point en commençant à inclure le temps de documentation dans vos estimations (même si honnêtement, je mets/met à jour/crée généralement des documents pendant que de longs processus sont en cours, tels que les compilations ou les enregistrements). 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 apportez d'un ancien lieu de travail (ce qui pourrait bien être le cas).
Attention: la plupart des patrons n'aiment pas faire les gens font quoi que ce soit, en particulier des choses qui ne sont pas directement liées à une tâche facturable, alors ne vous attendez pas à ce que ce soutien prendre la forme d'un mandat. Au lieu de cela, il est plus susceptible de vous donner un champ relativement libre pour écrire plus de documents.
4. Encouragez la documentation quand vous la voyez
Peut-être que l'une des raisons pour lesquelles les gens n'écrivent pas des documents aussi souvent qu'ils le devraient est qu'ils ont l'impression que personne ne les lit. Donc, lorsque vous voyez quelque chose que vous aimez, assurez-vous au moins de mentionner que vous êtes content qu'il soit disponible.
Si votre équipe effectue des révisions de code, c'est un moment où vous pouvez déposer un mot subtil ou deux pour encourager les bons commentaires.
Merci d'avoir documenté la solution de contournement pour le bogue B dans le cadre G. Je ne savais pas à ce sujet, et je ne pense pas que j'aurais pu comprendre ce que vous faisiez sans cela là-dedans.
Si vous avez quelqu'un dans l'équipe qui est réellement enthousiaste à propos de la documentation, cela ne fait pas de mal de cultiver cette personne en allant au déjeuner ou au café et en veillant à offrir une petite validation pour contrer le découragement qu'ils peuvent ressentir en voyant le reste de l'équipe n'accorde pas autant d'importance à la documentation.
Au-delà de cela, 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 content qu'il ait soif, mais tout ce que vous pouvez faire est de remplir le bac.
Il y a deux facteurs principaux dans mon expérience:
Délais
La plupart des entreprises sont tellement déterminées par les dates que l'assurance qualité, la dette technologique et la conception réelle sont réduites juste pour que le chef de projet ne soit pas mauvais ou pour respecter un délai client absurde et trop promis. Dans cet environnement où même la qualité fonctionnelle est réduite, un investissement à long terme comme la documentation a peu de chance.
Modifier
Une meilleure pratique relativement nouvelle pour les développeurs consiste à réduire l'importance des commentaires. L'idée est que le fait de conserver les informations à deux endroits (le code [y compris les tests] et les commentaires autour du code) entraîne beaucoup de temps supplémentaire pour les garder synchronisées pour un faible bénéfice. "Si votre code est si difficile à lire que vous avez besoin de commentaires, ne serait-il pas préférable de passer du temps à nettoyer le code?"
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 gens reconnaissent que les exigences changent régulièrement. Avec l'utilisation généralisée du refactoring, l'organisation du code va changer de façon assez substantielle. Pourquoi passer du temps à documenter toutes ces choses qui vont changer? Le code et les tests devraient faire assez bien le travail.
Il y a un certain nombre de facteurs en jeu ici:
Un code bien écrit est sa propre documentation. Toutes choses étant égales par ailleurs, il vaut mieux écrire un code plus clair qui parle de lui-même, plutôt que plus de documentation. Faites cela, et vous devrez modifier moins de documentation lorsque vous modifiez ce code.
L'écriture de documentation est sans doute une compétence différente de celle de l'écriture de code. Certains développeurs de logiciels sont meilleurs que d'autres. Certains sont bien meilleurs pour écrire du code que pour la documentation.
La documentation ne doit être écrite que ne fois, pas deux fois (une fois dans le code source et de nouveau 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 être plus délicate et encombrante que la simple écriture manuelle de la documentation, c'est pourquoi vous ne voyez pas ces outils largement utilisés.
Une bonne documentation prend du temps et est difficile à bien faire. Toutes choses étant égales par ailleurs, il peut être plus utile d'écrire du nouveau code que d'écrire de la documentation pour du code déjà existant.
Lorsque le code change, vous devez également modifier la documentation. Moins il y a de documentation, moins il faut en changer.
Personne ne lit la documentation de toute façon, alors pourquoi s'embêter?
Éléphant dans la salle: les programmeurs ne sont pas (nécessairement) des écrivains. Ils ne sont pas non plus nécessairement prêts à étendre 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 de donner des détails utiles aux futurs développeurs (même si les développeurs daignaient les expliquer).
Un système complexe peut devenir presque impénétrable au fil du temps sans documentation appropriée. Le code perd moins de valeur inversement proportionnellement à sa capacité de contrôle [sic]. Résolu, la direction embauche un ingénieur logiciel qui peut lire le code et cajoler les détails des développeurs, le paie à un taux de développeur et le charge de documenter et de maintenir la documentation. Cet auteur peut lire le code et saura quelles questions poser et remplira les détails si nécessaire. Tout comme vous avez un département QA, vous avez un département de documentation interne.
Le code deviendra plus précieux, car vous pouvez le concéder sous licence à un tiers (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 prenez en compte les versions plus légères de votre logiciel et vous pourrez introduire plus facilement de nouveaux développeurs dans le projet, vos ingénieurs de support adoreront travailler pour vous.
Cela n'arrivera jamais.
Plus important encore, comment puis-je les convaincre que la rédaction de documents nous fera gagner du temps et de la frustration à l'avenir?
Est-ce que ça fait ça?
Il existe deux types de documentation:
Documentation utile
Documente comment utiliser un produit fini, une API, les adresses IP ou les noms d'URL de nos serveurs, etc. Fondamentalement, tout ce qui est utilisé de manière intensive et quotidienne. Des informations erronées seront découvertes rapidement et seront corrigées. Doit être trouvé facile et facile à modifier (par exemple Wiki en ligne).
Documentation inutile
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. Cette documentation prendra du temps à écrire et du temps pour découvrir qu'elle est erronée plus tard. Vous ne pouvez pas compter sur ce type de documentation. C'est inutile. Ça 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. Nous avons eu un succès retentissant avec cela dans mon dernier projet lors de l'introduction d'un Wiki où nous pouvions é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 à considérer:
Documentation produit/version
C'est tout ce qui sort avec votre produit "fini". C'est plus que de simples manuels, ce sont des LISEZMOI, des journaux de modifications, des HOW-TO et autres. En théorie, vous pouvez vous en passer de ne pas les écrire, mais vous vous retrouvez avec un produit que les gens ne veulent pas utiliser, ou un fardeau de support inutilement cher.
Documentation API
Ceci décrit quelque chose qui devrait être relativement statique. Étant donné que de nombreux consommateurs peuvent coder pour votre API, celle-ci doit être suffisamment stable pour qu'une prose décrivant comment l'utiliser l'ait. Décrire quels paramètres sont pris en charge, quelle peut être la valeur de retour et quelles erreurs peuvent être générées permettra aux autres utilisateurs de comprendre votre API au bon niveau d'abstraction - l'interface (pas l'implémentation).
Commentaires sur le code
L'opinion de l'industrie sur les commentaires semble en ce moment changer. Quand j'ai commencé à coder professionnellement, les commentaires étaient une condition sine qua non quand il s'agissait d'écrire du code. Maintenant, la mode est d'écrire du code si clair que les commentaires sont inutiles. Je suppose que cela est en partie dû au fait que de nombreux 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 dans l'assembleur. , C, FORTRAN, etc. Ainsi, les commentaires avaient une valeur beaucoup plus grande.
Je crois toujours qu'il y a de la valeur dans les commentaires qui décrivent l'intention d'une section de code, ou quelques détails sur la raison pour laquelle un certain algorithme a été choisi sur un plus évidente (pour éviter les démons de refactorisation trop zélés de "réparer" du code qui n'a pas réellement besoin d'être corrigé).
Malheureusement, il y a beaucoup d'égoïsme, de rationalisation et d'auto-illusion impliqués dans les décisions des programmeurs de ne pas documenter. La réalité est que, comme le code, le principal public de documentation est les autres personnes. Ainsi, les décisions d'écrire (ou de ne pas écrire) de la documentation, à n'importe quel niveau, doivent être prises au niveau de l'équipe. Pour les niveaux d'abstraction plus élevés, il peut être plus judicieux d'avoir quelqu'un d'autre que des développeurs pour le faire. En ce qui concerne la documentation au niveau des commentaires, parvenir à un accord sur l'objet et l'intention des commentaires doit être convenu ensemble, en particulier dans les équipes mixtes de compétences et d'expérience. Il n'est pas bon d'avoir des développeurs seniors qui écrivent du code que les développeurs juniors ne peuvent pas approcher. Une documentation bien placée et bien écrite peut permettre à une équipe de fonctionner beaucoup plus efficacement
Voici mes deux cents.
Le Manifeste Agile déclare "Logiciel de travail sur une documentation complète" et tout le monde ne lit pas pour atteindre "Autrement dit, alors que il y a de la valeur dans les articles à droite, nous valorisons davantage les articles à gauche. "
Malheureusement, il est courant de https://en.wikipedia.org/wiki/Code_and_fix et la documentation ne fonctionne pas avec ce modèle (il se désynchronise).
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.
Le code auto-documenté est la tendance actuelle.
Cela dit, je pense qu'il y a beaucoup de bonne documentation.
La lecture du code vous montre comment cela fonctionne. Cela ne peut pas expliquer pourquoi: vous avez besoin de commentaires.
La lecture du code vous montre le nom d'une méthode et les types de paramètres. Cela ne peut pas expliquer la sémantique ou 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 prend du temps, et je soupçonne que beaucoup de développeurs ont eu trop de rodages avec une documentation pire qu'inutile. Ils ont l'idée que non seulement la documentation leur causera des problèmes de la part de leur manager (le même gars qui continue de couper la partie QA du calendrier), mais cela n'aidera personne, y compris eux.
Toute documentation à moitié 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 la pensée de faire la documentation est extrêmement douloureuse.
La plupart des autres réponses passent sous silence qu'il existe au moins deux types de documentation: un ensemble pour les autres développeurs et un ensemble différent pour les utilisateurs finaux. Selon votre environnement, vous pouvez également avoir besoin de documentation supplémentaire pour les administrateurs système, les installateurs et le personnel du service d'assistance. Chaque public cible a des besoins et des niveaux de compréhension différents.
Considérez le développeur (stéréo-) typique: c'est un codeur par choix. Il a choisi une carrière hors 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 l'ensemble des compétences requises pour produire une bonne documentation est antithétique aux compétences requises pour produire un bon code.
Un bon rédacteur de documentation peut communiquer en plusieurs langues: la langue des utilisateurs, la langue de la gestion, la langue du personnel de support, la langue des développeurs. C'est le travail d'un rédacteur de documentation de comprendre ce qu'un codeur communique et de traduire cela sous une forme que tous les autres groupes peuvent comprendre.
Lorsque vous vous attendez à ce que les codeurs développent les compétences nécessaires pour devenir de bons communicateurs (écrits ou autres), le temps passé à perfectionner l'ensemble de compétences principal (codage!) Est diminué. Plus il s'éloigne de sa zone de confort (codage et communication avec d'autres codeurs), plus il faudra de temps et d'énergie pour bien exécuter la tâche. Vous pouvez raisonnablement vous attendre à ce qu'un codeur professionnel désire se concentrer principalement sur ses compétences de base, au détriment de tous les autres.
Pour cette raison, la documentation (à l'exception des commentaires de code en ligne) est préférable de laisser aux communicateurs, pas aux codeurs.
La documentation n'est pas exécutée comme le code l'est. Par conséquent, il n'y a 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 promu Literate Programming comme un moyen d'améliorer la qualité du logiciel, en écrivant efficacement la documentation avec le code. J'ai vu quelques projets qui ont utilisé cette approche assez efficacement.
Personnellement, j'essaie de m'en tenir à la tendance moderne de garder l'API publique de votre code aussi lisible que possible et d'utiliser des tests unitaires pour documenter l'utilisation pour 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 avec certains développeurs qui écrivent une documentation odieusement peu: ils ne peuvent pas taper. Si vous avez une approximation du système à 10 doigts, vous avez tendance à écrire plus de documentation simplement parce que c'est facile. Mais si vous êtes coincé avec la chasse et le picage, vous êtes perdu. Si je serais responsable de l'embauche, c'est en fait quelque chose que je vérifierais.
Les gens qui n'aiment pas lire la documentation n'aiment pas écrire la documentation. De nombreux programmeurs feront tout leur possible pour éviter de lire un document en profondeur.
Ne vous concentrez pas sur l'écriture, concentrez-vous sur la lecture. Lorsque les programmeurs lisent la documentation et en assimilent des éléments, ils en verront la valeur et seront beaucoup plus enclins à en écrire.