Rédaction d'un manuel du développeur à l'échelle de l'entreprise


17

Je travaille pour une petite entreprise. Le bras de développement logiciel de l'entreprise avant mon embauche était composé d'un gars surmené autodidacte. Maintenant que j'écris des logiciels pour l'entreprise depuis quelques années, j'ai été chargé d'établir des pratiques formelles de développement de logiciels à l'échelle de l'entreprise. Nous n'avons actuellement aucune directive, à part

Écrivez du code, testez-le, mettez-le dans un fichier .zip et envoyez-le au client. Points bonus pour TDD et contrôle de version.

Mon patron veut que j'écrive un manuel du développeur de logiciels qui définit les processus généraux, les protocoles, les outils et les directives que nous utilisons pour faire avancer les choses. En d'autres termes, il veut un livre «C'est ce que nous faisons ici» pour faciliter la familiarisation d'un nouvel employé avec la façon dont nous faisons les choses, ainsi que pour aider mon patron à comprendre ce que font ses serviteurs et comment ils le font. il.

De la façon dont je le vois, je jette les bases et cela doit être fait correctement. Comment feriez-vous pour choisir des sujets pour un tel manuel? Pouvez-vous fournir quelques exemples de sujets?

Note latérale: Si cela importe, nous sommes principalement une boutique Microsoft .NET. Et nous examinons des pratiques agiles telles que XP et Scrum, mais nous devrons peut-être les modifier considérablement pour les faire fonctionner dans notre entreprise.


3
Votre processus actuel est très pauvre. Avez-vous le soutien d'une entreprise pour modifier votre processus actuel, cela ne sera pas bon marché, le type de changement requis prendra de l'argent. Il y a beaucoup de livres sur le sujet, la plupart de ces pratiques ont des outils, qui sont nécessaires pour les implémenter d'une manière qui ne nécessite pas beaucoup d'efforts.
Ramhound

magasiner pour des sujets de manuel?
moucher

1
@gnat Bon point. Voir modifier.
Phil

bon montage (vous avez apparemment suivi le lien). Je changerais également Quels types de sujets pensez-vous qui sont importants ... à quelque chose comme Comment évalueriez-vous l'importance des sujets ... - de cette façon, ce serait plus conforme aux conseils de Jeff pour autant que je le comprenne
moucheron

1
Je ne suis pas vraiment préoccupé par la façon de mesurer l'importance des sujets, car je pense que je peux déjà le faire. Je cherche plutôt des exemples. J'ai toujours considéré que les réponses aux questions abstraites étaient meilleures lorsqu'elles étaient accompagnées d'exemples. Voir modifier. BTW, j'apprécie votre aide pour améliorer ma question.
Phil

Réponses:


20

Je le décomposerais en sections comme

  • Personnel actuel - noms et titres (idéalement avec photos)
  • Applications, identifiants, données à connaître et demandes d'autorisation à soumettre
  • Signets vers les sites de l'entreprise et les principaux sites externes pertinents pour l'entreprise
  • Applications que la société utilise pour les communications, le courrier électronique, la réservation de salle de conférence, l'écran partagé
  • Procédures pour les activités liées à l'entreprise telles que les reçus de dépenses, la réservation de voyages
  • Configuration de la machine développeur. Décrivez en détail le processus de configuration d'une nouvelle machine de développement. Il est généralement «attendu» que cela ne prenne qu'une journée, mais cela prend souvent 3 à 5 jours en réalité.
  • Le processus de développement, la façon dont le travail est suivi, attribué et mis à jour et quels outils sont utilisés.
  • Comment tester, quoi tester, quand tester, où tester.
  • Normes de codage, notamment les conventions de dénomination des fichiers et les normes spécifiques à la langue.
  • Comment gérer les bogues, où les documenter, comment les corriger.
  • processus de déploiement, quels sont les éléments clés à connaître pour les poussées de production.
  • Comment documenter, quoi documenter, quand documenter.
  • Où les choses «sont», par exemple les emplacements pour le code, les données, les normes, la documentation, les liens et autres actifs.

Le rendre modulaire vous permettra également, à vous ou à d'autres, de mettre à jour les éléments séparément, par exemple, les noms et les postes des employés changeront fréquemment à mesure que les gens vont et viennent.

Pour chaque section, je m'efforcerais de l'écrire du point de vue des «débutants». Le plus important sera de s'assurer que cela a du sens pour un débutant. Votre patron n'est évidemment pas la bonne personne pour revoir cela car il n'est pas le public visé. Il a raison de le vouloir, assurez-vous simplement que le contenu ne finit pas par être testé par lui. De plus, un "débutant" n'a que "1 semaine" comme débutant ... et n'a qu'un seul point de vue. Il est donc probable (et recommandé) que le document soit affiné avec chaque nouvel employé. En fait, c'est une assez bonne tâche de les assigner également pour leur première semaine, c'est-à-dire "Mettre à jour le manuel du débutant".

Pour Agile / SCRUM:

La partie la plus difficile de faire Agile et SCRUM est «vraiment» de le faire.

Pour lire, je commencerais sur http://agilemanifesto.org/ et j'irais de là.

Je voudrais également lire le célèbre http://www.halfarsedagilemanifesto.org/ qui ajoute du poids au fait que vous devez vraiment embrasser tous les aspects pour que cela fonctionne. Si vous devez modifier Agile en profondeur pour vos organisations, il est probable que les gens veulent les avantages - sans utiliser les processus appropriés. Ce fait lui-même devrait être présenté pour conjurer tout demi-assyness.


6
J'aime la fréquence à laquelle vous éditez ceci. Comment ... agile de votre part. :)
Phil

Nous ne voulons pas nécessairement modifier les principes agiles en général. Nous modifierions simplement des pratiques spécifiques telles que XP, car nous n'avons pas vraiment la main-d'œuvre pour implémenter tous les rôles requis. C'est peut-être une autre question pour un autre jour.
Phil

Désolé, j'ai supprimé la réponse pour l'instant car la question a été modifiée.
Phil

1
Points bonus si vous configurez un wiki d'entreprise pour contenir ces informations ...
Spencer Rathbun

Salut Spencer, c'est intéressant. Je viens également de commencer à utiliser un wiki github avec markdown. Toute réflexion sur la façon dont ils se comparent. De toute évidence, beaucoup de gens connaissent github grâce au code et au démarquage de SO, il est donc facile de se faire adopter.
Michael Durrant

4

Il semble que vous devrez introduire certaines pratiques avant de les documenter!

a) Contrôle des sources - comment stockez-vous vos sources et effectuez-vous le contrôle des révisions

b) Gestion et suivi des versions - comment faire une build, numéroter une version, comparer une version actuelle candidate à une version précédente

c) Gestion des problèmes - comment suivez-vous les bogues dans vos versions.

Ce sont des choses assez basiques mais elles peuvent prendre beaucoup de temps (et éventuellement coûter de l'argent) à mettre en œuvre.


2
+1 pour rester simple et se concentrer sur des questions importantes. Nous n'avons vraiment pas besoin de mandats de «gros gouvernement» sur les styles de codage.
kirk.burleson

3

Sujets que j'inclurais dans le manuel d'un développeur:

  • Rôles / postes au sein du département et leurs responsabilités correspondantes
  • Exigences logicielles de la machine du développeur (c.-à-d. Environnement de développement requis)
  • Où et comment accéder au référentiel de code source
  • Outils de développement utilisés (par exemple IDE)
  • Style / normes de codage
  • Normes de documentation
  • Processus de test
  • Processus de construction
  • Processus de déploiement
  • Processus de support et de gestion des problèmes
  • Où obtenir la version la plus récente de ce manuel

Gardez à l'esprit que ce manuel ne doit contenir que des éléments spécifiques au développement et non des informations à l'échelle de l'entreprise (qui doivent figurer dans le manuel de l'employé).


2

Utilisation du contrôle de source

  • Quel outil de contrôle de source vous utilisez.
  • Syntaxe des commandes / outils courants dans l'EDI.
  • Stratégie de branchement / fusion.
  • Quelle devrait être l'unité d'un commit? Combien de temps est trop long pour qu'un fichier soit extrait / non validé?
  • Quel niveau de «souplesse» dénote un commit / check-in? Compile? Les tests unitaires réussissent? Révisé?
  • Ce qui devrait être inclus dans les notes pour un commit / check-in.
  • Procédures de restauration.
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.