Comment puis-je documenter le travail passé de quelqu'un d'autre? [fermé]

Nous sommes dans une mauvaise situation d'avoir très peu de documentation sur la personnalisation que nos anciens employés ont faite pour un système critique pour l'entreprise. De nombreux changements ont été apportés à Crystal Reports, aux entités de base de données et aux fichiers de configuration / programmation propriétaires pour notre logiciel ERP.

La documentation actuelle se lit généralement comme suit:

Ce programme est exécuté avant la facturation. Bugs connus: aucun.

Exécutez ce programme après avoir installé le logiciel X.

Modification des champs suivants dans ce rapport: (sans explication sur comment ni pourquoi)

Notre magasin informatique est petit, et dans le cas du logiciel ERP, la plupart du travail était regroupé sur une seule personne (c'est moi maintenant), donc personne d'autre ici ne sait ce que nous avons fait. Le département informatique et comptable connaît les morceaux (parfois très utiles) mais ce n'est pas suffisant.

Un autre problème est que notre service comptable semble penser que nous sommes bien documentés. Il est vrai que nous avons conservé de nombreux enregistrements de ce qui n'a pas fonctionné , mais très peu explique ce qui (le cas échéant) a été fait pour résoudre ces problèmes. Nous avons des centaines de documents expliquant les bogues, mais les documents expliquant les changements (comme indiqué ci-dessus) sont presque inutiles.

Comment puis-je documenter les changements passés lorsque je ne sais pas tout ce qui a été fait? Je peux commencer par documenter ce que nous avons changé: fichiers, tables de base de données, etc. dont nous avons besoin pour que le système fonctionne. Je peux également documenter ce que nous faisons ; lorsque des rapports sont exécutés, pourquoi les gens ont été invités à utiliser le rapport / programme X. Mais quand une de ces choses personnalisées a un problème, je reviens toujours à la case départ.

Comment puis-je documenter ces informations de manière proactive pour moi et les autres?

Je pense que c'est un exercice futile. Si cela fonctionne, cela fonctionne, si cela ne fonctionne pas, vous devez le réparer.

La meilleure façon de documenter d'anciennes choses est de travailler dessus, de documenter ce que vous faites et d'expliquer la logique métier (qui, je suppose, n'a pas été documentée). Ce sera une grande aide pour tout nouveau développeur.

En parlant de documenter l'ancien code / les choses, quelqu'un devait le posséder. Supposons qu'il s'agit de votre gestionnaire actuel. Il / elle peut ne pas en avoir une connaissance technique complète, mais saura quels changements ont été apportés. Dans ce cas, ce n'est pas votre travail. Peut-être que le gestionnaire peut écrire quelque chose à ce sujet sur les modifications qui ont été apportées. Ce serait utile de garder l'histoire. Si un problème comme celui-ci survient, vous pouvez creuser dans ces domaines, cela pourrait vous être très utile. Mais entrer dans le code et documenter les changements est IMO assez inutile et probablement impossible.

Abandonnez vos efforts pour documenter les modifications .

Au lieu de cela, commencez à documenter ce qui fonctionne actuellement et comment . Gardez cette documentation à jour et à jour lorsque vous apporterez des modifications à l'avenir.

Avez-vous le contrôle des sources?

Pouvez-vous déterminer ce qui a changé depuis?

Si c'est le cas, vous pourrez peut-être mapper cela sur les changements commerciaux, qu'il s'agisse de nouvelles fonctionnalités ou de corrections de bogues.

Est-il possible de ressusciter une ancienne boîte aux lettres de développeurs? (Je ne sais pas si cela est viable avec des problèmes de confidentialité ou non). Il peut y avoir beaucoup d'informations à gagner en chalutant par là.

Tout d'abord. Où stockez-vous votre documentation? Si ce n'est pas déjà fait, créez un wiki. Je préfère dokuwiki moi-même, et il y a même un vm pré - construit , si vous êtes si enclin.

Cela fournit quelques fonctionnalités importantes:

• Les documents sont accessibles n'importe où sur le LAN de l'entreprise (installation sur un nouvel ordinateur ...)
• Tous les documents sont au même endroit
• Tous les documents sont consultables
• Vous pouvez collaborer (nouveau collègue, utilisateurs du logiciel)

Maintenant, si votre documentation est sur papier, je vous souhaite le meilleur. Si vous avez des documents Word, créez un script d'importation .

Enfin, utilisez simplement le truc . Chaque fois que vous devez installer quelque chose, mettez des notes dans le wiki. Si vous frappez un cas de bord, mettez-le dans le wiki. C'est là que la collaboration peut briller, car vous demandez à d'autres personnes de faire le travail pour vous.

En passant à une documentation plus spécifique, si vous avez besoin de travailler avec la source pour divers projets, assurez-vous que vous disposez d'un environnement de développement approprié ! Pour une liste de contrôle des choses que vous devriez avoir:

• Contrôle de version ( git , mercurial , fossil )
• Suivi des bugs ( trac , mante , redmine , fossile )
• Système de build ( autotools , scons , buildbot )
• Contrôle de projet ( éclipse , structure de répertoires spécifiée, plugin éditeur )
• Documentation source (README, TODO, INSTALL, Commentaires source)

Enfin, parce que la documentation peut être ennuyeuse, faites-en un jeu. Donnez-vous des "points" pour chaque élément de votre liste de contrôle, en vérifiant périodiquement votre "score". C'est un bon moyen de voir ce que vous avez accompli et à quel point. Il indique également où vous devez aller ensuite.

Considérez cela comme une opportunité d'apprendre beaucoup de choses sur la façon de mettre en place un environnement de développement approprié, et n'ayez pas peur d'essayer les choses et de passer à autre chose. Trouvez quelque chose que vous aimez et migrez l'environnement pour que les choses s'améliorent . Abordez cela comme un projet où vous cherchez à construire la meilleure solution.

Éditer:

Selon le commentaire ci-dessous, une autre chose utile à faire est de créer des diagrammes du code source. Le code libre contient des éléments , et cet article en répertorie certains pour les langues populaires.

Le mieux que vous puissiez faire est de documenter tout ce que vous savez et de demander à l'entreprise de documenter tout ce que les autres savent également. Je suggère de centraliser la documentation dans un wiki ou quelque chose de similaire afin que tout le monde ait accès à la documentation la plus récente.

Vous ne pouvez pas documenter quelque chose que vous ne savez pas, alors soit vous essayez d'apprendre et de découvrir pourquoi quelque chose a été fait, soit vous le laissez sans document. C'est pourquoi l'entreprise a besoin de prendre davantage soin de documenter les choses pendant que ceux qui savent y sont encore employés.

Si vous essayez de documenter un code que vous ne comprenez pas, je vous suggère d'écrire des tests unitaires pour tester la fonctionnalité. De cette façon, vous comprendrez mieux ce que fait le code et les tests eux-mêmes peuvent servir de documentation.

Bonne chance!

Lorsque j'essaie de documenter quelque chose que quelqu'un d'autre qui n'est plus avec le projet ou l'entreprise a fait, je commence toujours l'attitude de: C'est une boîte noire pour tout le monde, y compris moi, jusqu'à ce que je doive changer quelque chose ou l'expliquer à quelqu'un d'autre.

La raison pour laquelle ce projet se présente sous la forme de documentation dans laquelle vous l'avez trouvé est que la documentation de tout travail est quelque peu secondaire à son exécution. Donc, documentez ce que vous changez et si vous avez compris ce que le champ particulier de la base de données et quel bloc de code particulier fait, si ce n'est pour le bénéfice de personne d'autre que le vôtre.

Vous pouvez écrire des tests exploratoires automatisés. Ceux-ci présentent plusieurs avantages:

• Vous apprenez comment fonctionne le système au fur et à mesure que vous les écrivez

• Ils servent de documentation exécutable pour plus tard

• Si vous les exécutez régulièrement ou même en continu, ils fournissent un joli filet de sécurité pour détecter quand les changements cassent quelque chose ou quand ils doivent être mis à jour

Je ne sais pas s'il est possible d'écrire ce genre de tests dans votre environnement particulier.