Quelle est la documentation * projet * la plus utile que vous avez rencontrée?

Question

J'ai un gros problème avec la mise à jour de la documentation, d'autant plus que l'infrastructure sous-jacente de mon application subit de nombreux changements au cours des premières étapes du développement. Je trouve qu'il est très difficile de documenter une cible en mouvement. Cependant, cela peut compliquer un peu les choses pour les nouveaux développeurs qui viennent juste d'arriver au projet, car toute la documentation n'est invariablement qu'à moitié correcte. Etant donné que je n'arrive déjà pas à tout documenter, j'ai décidé qu'il était préférable de documenter les fonctionnalités les plus importantes de mon projet.

Ma question est vraiment:

• Quelles sont les qualités d'un document utile qui aidera un développeur venir à la vitesse sur un nouveau projet et leur permettre de commencer rapidement faire des contributions précieuses?

Combien de temps devrait-il être? Quel type d'information était inclus? Quel niveau de détail? Quel type d'UML?

Remarque: Les liens vers des exemples de documentation d'API ne m'intéressent pas. Vraisemblablement, le développeur moyen peut lire et comprendre le code.

Answer 1

Pour répondre à la question en gras.

Je pense que la documentation fonctionnelle est la meilleure. Ne dites rien sur ce qui est sous le capot. Expliquez simplement ce que fait le programme. Une fois que le programmeur comprend le domaine, il aura un meilleur contexte pour évaluer les abstractions qui ont été faites dans le code.

Joel a des spécifications series on functional que vous pouvez consulter.

Answer 2

Nous avons un document intitulé "Exigences de validation"

Ce document est la vue d'ensemble de haut niveau d'une caractéristique et contient:

• Exigences d'activité Aperçu
• Aperçu des fonctionnalités
  • Wireframes de nouveaux éléments de l'interface utilisateur/Modifications
    • Chaque page qui va changer devrait avoir une structure filaire décrivant les changements et les faits saillants des nouveaux éléments interactifs
  • Règles d'affaires à prendre en compte pour les éléments non UI.

Ce document est habituellement livré avant la spécification officielle et est utilisé pour la répartition initiale du travail. Cela nous permet d'avoir un aperçu de haut niveau de tout ce qui est nécessaire pour la nouvelle fonctionnalité et nous pouvons commencer à penser aux cas limites et aux failles de spécifications tôt.