Comment documenter un projet déjà développé?

Je voudrais savoir quelles options sont disponibles pour documenter un projet qui a déjà été développé, car les développeurs qui ont travaillé n'ont pas écrit une seule page de documentation.

Le projet n'a pas d'autres détails que de nombreuses pages de scripts avec des fonctions écrites et modifiées par les développeurs qui ont travaillé sur ce projet au cours des 2 dernières années. Tout ce que j'ai, c'est le schéma de la base de données et les fichiers de projet. Je voudrais savoir s'il existe un moyen d'organiser ce projet et de le documenter afin qu'il puisse être utile pour les développeurs qui travailleront sur ce projet à l'avenir.

Le projet a été développé avec PHP et MySQL. Les fonctions sont mal commentées, donc je ne peux pas obtenir de bons résultats lorsque je l'exécute avec doxygen.

Qui lira la documentation? À quoi servira la documentation? Ce sont les questions les plus importantes auxquelles répondre. Par exemple, la documentation destinée aux développeurs de maintenance se concentrerait davantage sur la structure, tandis que la documentation destinée aux développeurs intégrant le produit se concentrerait davantage sur les services Web et la structure de la base de données.

En général, faites autant de documentation que nécessaire et pas plus. De nombreuses organisations ont besoin de documentation parce que quelqu'un a insisté sur le fait que c'était la meilleure pratique, mais la documentation finit par s'accumuler.

En supposant que les gens utiliseront réellement la documentation, n'essayez pas de capturer le code et la base de données au plus petit niveau. Les développeurs examineront le code pour les minuties. Au lieu de cela, concentrez-vous sur des détails qui ne sont pas apparents dans le code , par exemple:

1. Les cas d'utilisation rencontrés par le produit. Cela peut être difficile compte tenu de l'âge du produit, mais saisir ce que le produit est censé faire donne un contexte vital aux lecteurs et aux testeurs non techniques. Quels sont les concurrents sur le marché (le cas échéant)? Y a-t-il des éléments exclus de la portée du produit?
2. Toutes exigences claires non fonctionnelles . Par exemple, le produit a-t-il été écrit pour gérer un certain volume? Quel âge peuvent avoir les données? Où la mise en cache est-elle utilisée? Comment les utilisateurs sont-ils authentifiés? Comment fonctionne le contrôle d'accès?
3. Un diagramme de contexte montrant l'interaction avec d'autres systèmes, tels que la base de données, les sources d'authentification, la sauvegarde, la surveillance, etc.
4. (Si connus) Risques et comment ils ont été atténués avec un registre de décision . Cela est probablement difficile rétrospectivement mais il y a souvent des décisions critiques qui influencent une conception. Capturez tout ce que vous connaissez.
5. Modèles de conception communs ou directives de conception . Par exemple, existe-t-il un moyen standard d'accéder à la base de données? Existe-t-il une norme de codage ou de dénomination?
6. Chemins de code critiques , généralement à l'aide de diagrammes de flux ou d'activités ou de diagrammes de séquence UML. Il n'y en a peut-être pas dans le projet, mais ce sont généralement ceux que les utilisateurs professionnels ont articulés.

Même si toutes ces informations ne sont pas disponibles, commencez dès maintenant . Les développeurs qui viendront après vous vous remercieront.

De bons tests unitaires automatisés ou des cas de test peuvent également être une documentation utile, bien que difficile d'accès pour les personnes moins techniques.

Il semble également que vous deviez apporter un changement culturel pour inclure la documentation . Commencez petit, mais, idéalement, le projet ne doit pas être «terminé» tant qu'il n'a pas au moins un niveau minimal de documentation. C'est probablement l'étape la plus difficile, car ce qui précède sont des choses que vous pouvez contrôler. C'est quelque chose que les autres doivent acheter. Cependant, cela peut également être le plus gratifiant, en particulier si le prochain projet que vous réalisez est accompagné d'une bonne documentation.

Dans le passé, j'ai géré une situation comme celle-ci en m'asseyant avec les différents propriétaires de produits ou utilisateurs avancés, en examinant leurs principaux cas d'utilisation et en les documentant avec un ensemble de tests. Vous pouvez les utiliser comme référence pour le système lorsque vous commencez à apporter des modifications à l'avenir. Cela peut également aider à identifier les zones du système qui n'ont pas de propriétaire ou de cas d'utilisation et qui sont potentiellement supprimées.

Tout dépend vraiment de la taille du système. S'il s'agit d'un système complexe avec de nombreuses parties prenantes différentes, vous pouvez créer un diagramme de composants de haut niveau détaillant les capacités existantes et où elles sont satisfaites. Cela peut être très utile pour identifier les problèmes architecturaux dans la conception du système.

En général, je suggère d'éviter la documentation à l'ancienne, car elle deviendra obsolète et il manquera des développeurs principaux à l'avenir. J'essaie toujours de produire une documentation vivante sous forme de tests qui seront maintenus à mesure que le système évolue.

Tout d'abord, quel est votre public cible? Futurs développeurs ou autres gens d'affaires? Avec la réponse à cette question à l'esprit:

Comme d'autres l'ont dit, une description de haut niveau est la première chose dont vous avez besoin. Expliquez ce que le système essaie de faire dans le cadre plus large des choses. Expliquez sur quoi il fonctionne, comment il s'intègre dans le réseau et parle à tout autre système. Ensuite, je parcourais chaque écran, le capturais et donnais une explication rapide de ce que fait l'écran et de la façon dont il interagit avec les autres parties du système. Si c'est pour les développeurs, restez conversationnel comme si vous leur expliquiez l'application pour la première fois. Après tout, c'est le but du doc ​​(je suppose).

Tout traitement ou logique compliqué j'utiliserais un diagramme d'état, un diagramme de flux de données ou un diagramme de séquence. Certainement faire un diagramme d'entité, puis une conception de schéma de base de données (deux choses différentes!). Peut-être un diagramme de classe de base mais restez simple, notez seulement les choses principales qui vous intéressent, les développeurs peuvent comprendre ces choses en regardant le code.

Si vous rencontrez des problèmes pour démarrer, faites comme s'il y avait un autre développeur dans la pièce juste à côté de vous, qui ne connaît pas la première chose sur le système, je suis relativement impatient et j'ai juste besoin de savoir l'essentiel. Ensuite, commencez à expliquer et notez ce que vous dites :)

Les suggestions précédentes sont toutes bonnes, mais j'envisagerais également de rechercher si votre communauté d'utilisateurs a créé elle-même une documentation ad hoc. Votre question ne précise pas si une version de votre «produit» (existant depuis deux ans) a déjà été mise à la disposition des utilisateurs. S'il a été utilisé et qu'il n'y a pas de documentation officielle, alors aucune documentation n'a été nécessaire, ou il existe un document «non officiel» qui peut être rudimentaire, mais aussi probablement perçu comme essentiel par les utilisateurs. Essayez de rechercher sur le Web des artefacts susceptibles de représenter des API critiques, des forums de recherche, demandez aux utilisateurs expérimentés et recherchez des sites de questions et réponses. Si possible, essayez d'écrire une documentation qui répond à un besoin technique ou commercial.

La question est, voulez-vous le documenter tel qu'il est maintenant ou tel qu'il devrait être?

Ce que j'ai lu de votre question, c'est que vous pensez à la documentation de l'API et pas tellement à la documentation utilisateur et que le code n'est peut-être pas si bien entretenu et cryptique.

Je crains que si vous documentez maintenant, vous finirez par jeter la plupart de votre travail une fois le code refactorisé.

Je prendrais l'approche suivante:

• rendre la documentation inutile autant que possible en adhérant aux meilleures pratiques courantes. Choisissez de bons noms de classe, des noms de méthode, des noms de variables que vous pouvez comprendre intuitivement
• décomposer d'énormes classes et / ou fonctions de monstres là où cela a du sens
• utiliser les commentaires PHPdoc - vous pouvez utiliser des outils pour créer de la documentation API
• écrire des tests pour cela: les tests vous aideront à comprendre ou à définir ce que le code doit faire.

Maintenant, vous avez encore des choses non documentées: ce peuvent être les concepts généraux, l'architecture, etc. Pour cela, j'écrirais en fait de la documentation - mais j'écrirais seulement ce qui est vraiment utile et utile.