Comment maintenez-vous la documentation de référence à jour?

Question

Je fais encore un autre PHP Framework pour le plaisir et le sport, et je fais les premiers tours de la documentation. J'ai l'intention de coder un peu, documenter ce que j'ai codé, coder davantage, ajuster les documents pour refléter les nouvelles capacités du code, répétez. Par exemple, la configuration est assez manuelle et fastidieuse pour le moment, mais je la documente car elle doit être configurée comme elle l'est aujourd'hui. Une fois que j'aurai automatisé la configuration, je prévois de réécrire ces parties pour refléter l'état actuel.

Ce que je me demande, y a-t-il des heuristiques pour garder la documentation de référence à jour? Je ne suis pas juste parlant de documenter l'API (quel genre de vient gratuitement avec PHPDoc et les goûts), mais aussi le plus grand schéma; les tutoriels, aperçu-articles-tout. Y a-t-il de bons moyens pour minimiser la chance d'oublier de mettre à jour quelque chose de spécial?

Answer 1

Ceci est un problème très difficile à cause de la délocalisation: Les informations d'un élément de documentation peuvent dépendre ou affecter plusieurs emplacements de code, et lorsque vous consultez l'emplacement du code, vous ne connaissez généralement pas la documentation. Ainsi, une modification du code peut ne pas déclencher une mise à jour de la documentation, même si l'utilisateur aurait été disposé à le faire.

Je pense qu'il est important d'inclure une forme de liens explicites avec chaque section de code dans laquelle une modification entraînerait un changement dans la documentation. Il est difficile d'amener les utilisateurs à mettre à jour le texte. Il est donc difficile de trouver les zones susceptibles d'être affectées, en particulier pour les documents plus généraux (par exemple, une API)

Si je mets à jour une fonctionnalité mentionnée dans plusieurs endroits, j'ai besoin de cette liste pour au moins avoir une idée de l'endroit où chercher un besoin potentiel de mise à jour.

Answer 2

Nous avons fait quelque chose de similaire dans mon premier emploi.

/* 
<document> 
    <version>x.y.z.g</version> 
    <date>10.4.2009</version> 
    <key>fff#ggg</key> 
    <more...................../more> 
</socument> 
*/ 
int ggg(char x){ 
... 
... 
} 

L'application Documenter testera la différence de dates (et dans les versions ultérieures, contre notre contrôle de code source) et soulèverait un drapeau d'avertissement lorsqu'il soupçonne un décalage.

En PHP, il ne devrait pas être trop difficile de construire quelque chose pour analyser les remarques de code, si elles sont conservées dans un format pré-connu et pratique.