Quel niveau de documentation pensez-vous que les développeurs vous fourniront?

Tout est dans le titre.

Il peut parfois arriver que le développement et l'informatique soient à couteaux tirés sur ce genre de chose. À quel niveau de documentation vous attendez-vous lorsque vous devez installer, corriger, maintenir, démarrer, arrêter et diagnostiquer une solution exécutée sur un ou plusieurs serveurs?

Toutes ces choses doivent être documentées en détail, bien que lorsque l'opération est standard pour le système d'exploitation, le serveur d'applications, le serveur Web, etc., vous pouvez supposer que les opérations informatiques savent comment le faire.

Installation: documentez tout sur la façon dont il est installé et configuré, y compris comment savoir s'il fonctionne correctement.

Parlez-nous de l'architecture, en particulier de la communication entre les différents composants de la solution (par exemple, la plage de ports - les mécanismes RPC utilisent souvent une plage de ports - nous devons savoir quelle est la plage et quand l'application peut manquer de ports).

Correctif: documentez tout ce qui est spécifique à l'application - ce qui doit être arrêté avant le correctif et toutes les actions de suivi après le correctif (caches, index, proxys qui peuvent avoir besoin d'être effacés ou reconstruits).

Maintenance: documentez à quoi ressemble un fonctionnement normal et anormal - quelles files d'attente et autres choses doivent être surveillées et quelle est leur plage normale.

Dites-nous comment gérer les données - en particulier les tables et les fichiers qui se développent sans limite (par exemple, les fichiers journaux et les historiques des transactions). Comment doivent-ils être purgés et quel est l'impact de la suppression des anciennes entrées? (sur les rapports, etc.).

Dites-nous comment effectuer des actions standard de gestion «comme d'habitude» / dans la vie - cela peut être l'ajout ou la modification de comptes d'utilisateurs, par exemple.

Parlez-nous de toute autre action de gestion régulière qui pourrait être nécessaire (par exemple, quels certificats sont utilisés et que faire à leur expiration).

Pour toutes les modifications, dites-nous comment les annuler (toutes les modifications ne sont pas réussies). Et dites-nous que vous avez testé les plans de restauration!

Diagnostic: documentez les formats et les emplacements des fichiers journaux et CHAQUE message d'erreur d'application qui pourrait apparaître, indiquant ce que le message d'erreur signifie qui a mal tourné et ce qui pourrait devoir être modifié pour y remédier. N'utilisez jamais le même message d'erreur pour deux événements différents.

Abattu et démarré: comment, dans quel ordre, toute procédure spéciale (par exemple, laisser les serveurs vider les connexions avant de les fermer).

Je ne suis pas du tout d'accord pour dire que la meilleure façon de procéder est de jeter l'application par-dessus la clôture et de laisser les informaticiens déterminer ce dont ils ont besoin. La documentation opérationnelle (et en général, les fonctionnalités de gestion de l'application) doit être pensée à l'avance.

Une question de suivi serait: que se passe-t-il lorsque (pas si) les développeurs ne fournissent pas une documentation suffisante?

Je recommande au service informatique de saisir des rapports de défauts sur le logiciel, en utilisant le système de suivi des défauts utilisé par les développeurs. De cette façon, s'ils ne vous ont pas dit, par exemple, que les fichiers dans un dossier particulier doivent être purgés et que seule une semaine devrait être conservée, vous pouvez entrer un défaut disant que "l'application remplit le disque avec des fichiers journaux ", et leur suggérer de travailler avec l'informatique sur une technique documentée pour purger ce dossier.

Ma liste d'exigences pour la documentation serait (pas dans un ordre spécifique):

(documentation sur :)

• tous les commutateurs de ligne de commande
• tous les états de sortie et valeurs de retour
• consigner les messages (pas tant le contenu que l'explication des champs s'il n'est pas configurable)
• syntaxe de configuration
• commutateurs dans les fichiers de configuration
• utilisation de la mémoire
• est-il fileté ou fourchu
• quels sont les signaux sur lesquels le serveur réagit
  • y a-t-il un signal qui ne redémarre pas le serveur mais le fait de relire la configuration
  • comment se comporte-t-il? (attend-il que les threads / processus existants se terminent avec l'ancienne configuration. Est-ce qu'il les tue, ...)
• ce qui se passe lors d'un arrêt impur (surtout s'il s'agit d'une sorte de service / serveur de persistance)
• se connecte-t-il via les appels fournis par le système ou se connecte-t-il avec quelque chose écrit par lui-même ( beurk pour apache et journal d'accès - je préfère clairement les outils embarqués pour la journalisation)
• Prêt pour IPv4 et IPv6 s'il s'agit d'un service réseau
• documentation sur le tronc et documentation sur une version spécifique
  • rien n'est aussi mauvais que de configurer quelque chose pendant des heures juste pour le découvrir sera ignoré car l'option de configuration n'est disponible que dans le coffre
• quelle option de configuration est valide dans quelle version (disponible depuis: v1.0, obsolète depuis: v1.2 ou quelque chose de similaire)

Une documentation comme celle-ci sont des exemples de bonne documentation:

• http://httpd.apache.org/docs/2.2/
• http://www.postgresql.org/docs/8.3/static/index.html

Je considérerais qu'une telle documentation est pleine d'échecs:

• http://tomcat.apache.org/tomcat-6.0-doc/index.html

Le manuel FreeBSD est également un excellent exemple de documentation et d'approche d'OpenBSD. Ils expulsent des choses qui ne sont pas correctement documentées.

EDIT: cette liste n'est en aucun cas complète, c'est juste le truc de base qui m'est immédiatement venu à l'esprit. De plus, la documentation doit être bien lisible, pas seulement quelque chose qui ressemble à quelqu'un qui a vomi .

En bref, j'attends la documentation que je spécifie et pour laquelle je contracte.

Trop souvent, ce détail essentiel est exclu d'un accord. L'utilisateur final l'attend et le veut gratuitement bien sûr. Les bons développeurs corrigeront cette erreur tôt dans le processus et établiront des attentes, y compris une exigence de prix et de temps.

Je crois que l'informatique doit communiquer avec les développeurs quel type de documentation est nécessaire. La meilleure façon de le faire est que le développement fournisse des versions préliminaires (ou des versions d'itération) d'une solution pour que l'informatique puisse jouer et tester afin que l'informatique puisse répondre avec ce qui est nécessaire.

La création de notes de version adéquates avec une application serait un bon début. S'il y a des changements dans le comportement actuel avec la version, toutes les notes de QA sur les changements dans les dépendances ou les comportements de démarrage / arrêt, les changements de charge sur les serveurs ou bases de données dépendants, etc.

@Spoike (je ne peux pas encore commenter les réponses ..)

Les implémenteurs informatiques (le rôle variera selon le type et la taille de l'entreprise) doivent travailler de manière cohérente pour atteindre les objectifs suivants:

• Configuration minimale requise pour l'installation / le renouvellement - en d'autres termes, l'informatique ne peut pas être passive et s'attendre à ce que les développeurs "sachent" quelles informations sont nécessaires au moment de l'installation / du renouvellement. J'ai constaté qu'il y a souvent une confusion / désaccord considérable en informatique quant à ce qui constitue une documentation appropriée d'une application. Dev comprend les exigences (nous l'espérons) et l'informatique doit caucus pour trouver ce qui - au minimum - est requis.

• Une procédure d'installation / de rotation - dans les paramètres d'entreprise, vous pouvez appeler ce changement de contrôle ou de gouvernance, mais il s'agit essentiellement d'un cycle d'examen standard dans lequel l'informatique s'assoit avec Dev PRIOR top install pour obtenir un briefing sur le produit et ses besoins.

L'installation d'une application n'est pas sans rappeler le lancement d'une production théâtrale. Avant que le rideau ne se lève, le réalisateur (développeur principal) rencontre à plusieurs reprises l'équipe de production de la scène (réalisateurs informatiques) pour s'assurer que tout est "juste" pour la soirée d'ouverture (l'installation publique).

Vous ne pouvez pas changer le personnage du développeur (pourquoi voudriez-vous le faire?), Mais vous pouvez indiquer votre objectif commun d'une application fantastique qui fonctionne à une vitesse fulgurante pour tous les utilisateurs. Vos exigences consensuelles en matière de documents informatiques ne sont que l'une des choses nécessaires pour garantir cela.