La documentation dégradante - comment y faire face?

Important : nous n'avons aucun problème avec la documentation du code source . Cela appartient à l'audit de code régulier et est tenu à jour. Notre problème est avec la documentation des développeurs (ou, "externe" si vous le souhaitez), de petits conseils de programmeurs aux programmeurs qui ont tendance à être une fois écrits, souvent laissés pour compte.

Nous utilisons un système de type wiki pour produire de la documentation pour les programmeurs - des articles écrits par des programmeurs pour des programmeurs décrivant un peu plus en détail le fonctionnement d'un morceau de code particulier. Ces pages wiki incluent généralement:

• les motivations derrière les décisions de conception pour certaines parties de l'API (par exemple; nous avons fait cette chose moche parce que cette bibliothèque tierce particulière veut que les choses soient faites de cette façon, parce que cette autre bibliothèque ..., parce que ...)
• explication de la façon dont nous traitons certaines tâches courantes (par exemple; affichage d'une fenêtre contextuelle triviale, qui doit référencer les styles d'application appropriés, s'inscrire dans le composant de registre et implémenter une interface afin d'être automatiquement "analysé" par un autre composant)
• bonnes pratiques (aussi subjectives soient-elles, nous écrivons ces trucs)
• configuration de l'environnement, outils requis et son installation

En général, principalement des éléments liés à l'écriture de code qui ne correspondent pas à la documentation de code habituelle en raison de sa taille et de sa nature de blog / article.

Le problème

En ce qui concerne l'introduction de ce système qui semblait être une bonne idée il y a quelques mois, j'ai aujourd'hui l'impression qu'il cause plus de problèmes qu'il n'en résout. Par exemple:

• les gens font écrire des articles ... mais une fois changé le code, la mise à jour du wiki suit rarement
• beaucoup d' articles à gratter , écrits par quelqu'un pressé et partis comme ça
• même si la demande d'article provient généralement du chef de projet, son exactitude / composition est rarement vérifiée - ce qui entraîne parfois une mauvaise qualité

La dégradation habituelle. Le code a changé, le wiki reste le même. La prochaine fois que quelqu'un cherche des informations, ce qu'il trouve habituellement est un tas de choses obsolètes et de mauvaise qualité - et se demande ce qui se passe, si les choses qu'il a trouvées sont exactes ou (pire encore) quelles parties en sont. Et ce qui était censé aider, finit par faire le contraire.

Pour le moment, il semble que les gens soient conscients du problème, chef de projet inclus, mais apparemment, personne ne semble être dérangé de faire quoi que ce soit avec cela (ou a des choses plus intéressantes à faire).

Ma pensée initiale était de jeter tout cela dans l'oubli (après avoir été mordu par des "conseils" obsolètes plusieurs fois de suite), mais je suppose que cela pourrait être trop extrême. Certaines informations méritent d'être notées et bien lues parfois, mais le problème est toujours le même: comment gérez-vous leur "actualité" ? L'avez-vous lié au code source d'une manière ou d'une autre (donc lorsque la version mise à jour du fichier est archivée, l'auteur de l'article est informé qu'il pourrait avoir besoin de réviser le code / l'article)? Une personne désignée l'a-t-elle "surveillée" sur les bases quotidiennes? Faites des nettoyages réguliers?

Il semble que vous documentiez trop de futilités dans le wiki.

Documentez les blocs de code et les méthodes dans le code . Essayez de rendre votre code auto-documenté afin de ne pas avoir à faire beaucoup de commentaires. L'écriture de tests unitaires peut également aider.

Documentez les décisions de conception et l'architecture à une granularité plus élevée dans le wiki afin que le wiki n'ait pas besoin de changer souvent ou de prendre beaucoup de travail pour changer. Si de nombreuses personnes de votre équipe connaissent déjà l'architecture et que l'équipe ne se développe pas rapidement, il peut ne pas être du tout justifié de les documenter, le face à face est souvent le meilleur transfert de connaissances.

Réécrivez ou supprimez immédiatement les informations obsolètes , comme un code mort, plus il reste longtemps, plus il devient difficile à repérer et plus il s'accumule. Si vous n'avez pas le temps, supprimez-le et marquez l'article comme devant être retravaillé, cela vous ralentit et est de toute façon stocké dans le contrôle de version.

Documentez les procédures en les automatisant dans un script ou un fichier d'installation. Sinon, conservez-les dans le wiki, mais chaque fois que quelqu'un utilise une procédure du wiki, dites-lui d'essayer d'améliorer l'article ou d'automatiser des parties du processus.

Les articles de blog appartiennent aux blogs . Si les gens veulent partager leurs opinions et conseils personnels, créez un blog d'entreprise pour cela. Ils ne veulent probablement pas que leurs articles soient modifiés et personne ne les modifiera de toute façon, alors ne les laissez pas encombrer le wiki.

La documentation doit être traitée comme un livrable et donc soumise aux règles de traçabilité et d'acceptation, et compte tenu du temps approprié à développer.

Il n'est pas rare de voir des gens "s'attendre" à ce que la documentation du logiciel soit une donnée, alors que ce n'est pas le cas.

Radical mais efficace. Si quelqu'un a écrit un nouveau module mais ne l'a pas documenté - rouvrez la tâche dans issue tracker et si cela est nécessaire, évitez d'envoyer tout le code source non documenté. Si vous autorisez les développeurs à traiter la documentation du code source comme un mal nécessaire, vous vous retrouverez avec des fragments de documentation fragmentaires et obsolètes.

Dans mon récent projet, nous avons au moins tendance à suivre toutes les bibliothèques tierces nécessaires. Si quelqu'un introduit une nouvelle bibliothèque, mais qu'elle n'est pas documentée - nous annulons la solution jusqu'à ce que la documentation soit introduite. Sans une approche aussi radicale, il y aurait chaos. Par exemple, un développeur inexpérimenté pourrait utiliser une bibliothèque dont la licence est en conflit avec la licence de notre logiciel.

Si quelque chose change rapidement, il ne devrait pas être conservé en dehors du code.

motivations derrière les décisions de conception pour certaines parties de l'API

Ceci est particulièrement important pour rester proche du code. Comme dans, dans le même fichier source. De cette façon, il sera un peu plus difficile d'ignorer chaque fois que quelqu'un touche le fichier et de demander moins de soumissions à TheDailyWTF par des personnes qui ne savent pas que la documentation externe existe.

La dégradation habituelle. Le code a changé, le wiki reste le même.

C'est là que la «documentation exécutable» - les tests unitaires - devient très utile. Si le code change et que les tests ne changent pas en même temps, alors la construction s'arrête. Bien sûr, écrire des tests en tant que documentation demande des compétences. Mais il en va de même pour la rédaction d'une (bonne) documentation externe.

Un bon moyen de résoudre le problème est de l'intégrer au processus. Si vous avez une trace de code jusqu'à / référence les pages pertinentes sur le wiki, un développeur peut facilement trouver ce qui pourrait avoir besoin d'être mis à jour. De plus, responsabilisez les réviseurs dans une révision de code pour vous assurer que le wiki est à jour (en ce qui concerne la mise à jour).

Une autre façon de l'ajouter dans le cadre du processus - puisque vous utilisez un modèle agile, faisant partie du processus de planification des itérations, pourrait être de mettre à jour les modifications prévues dans le wiki. Le wiki sert alors de ressource «voici comment les choses devraient fonctionner».

Si vous utilisez un langage .net, regardez ( Sandcastle ) qui prend la documentation XML (/// en C #) et la convertit au format d'aide MSDN.

Le format comprend une description, des commentaires et a la capacité d'inclure des exemples de code, ainsi que d'autres fonctionnalités. Vous pouvez effectuer une sortie aux formats .CHM, .HsX, .MSCH et HTML / ASP.NET. Le projet réel est ajouté à votre solution et construit sur le serveur de génération. Nous l'avons fait et déployé sur un site Web à chaque version, et les consommateurs l'adorent car la documentation est pertinente pour la version et constamment mise à jour.

Vous pouvez également spécifier les éléments à inclure dans la documentation. Actuellement, nous avons 2 projets: un pour les consommateurs externes qui comprend uniquement les contrats et les éléments appropriés (classes, énumérations, etc.), et un pour les développeurs internes qui inclut tout dans l'API, y compris les éléments marqués privés et internes.

C'est devenu la seule documentation que nous utilisons, car les motivations et les bizarreries liées à l'utilisation de l'API peuvent être incluses dans la section Commentaires de la documentation. Le processus fonctionne bien là où je travaille.

Je me concentrerais sur deux domaines, 1) Le code. 2) Notes et document sans code.

1) Le code.

Essayez de le rendre auto-documentation. Dans le passé, j'ai trouvé que c'était souvent conseillé mais rarement bien expliqué, alors ...

Au lieu de ce genre de pseudo-code:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Faites du code qui ressemble plus à ceci:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Utilisez le contrôle des sources pour suivre les informations «qui a fait quoi et quand».

2) Le non-code

Utilisez un wiki et un format de démarque pour conserver ces informations. Faites-en une partie du travail. Faites-en la publicité, postez-le et bloguez-le. Organisez une réunion hebdomadaire ou mensuelle standard pour examiner les éléments anciens et nouveaux. Faites-en un mantra que lorsque quelqu'un demande quelque chose, la réponse est donnée ... avec la pensée "cela devrait-il être dans le wiki pour la prochaine fois que quelqu'un demande?"