Erstellen eines unternehmensweiten Entwicklerhandbuchs

17

Ich arbeite für eine kleine Firma. Die Software-Entwicklungsabteilung des Unternehmens bestand vor meiner Einstellung aus einem überarbeiteten Autodidakten. Nachdem ich einige Jahre lang Software für das Unternehmen geschrieben habe, wurde ich beauftragt, formelle unternehmensweite Softwareentwicklungspraktiken zu etablieren. Wir haben derzeit keine anderen Richtlinien als

Schreiben Sie Code, testen Sie ihn, speichern Sie ihn in einer ZIP-Datei und senden Sie ihn an den Client. Bonuspunkte für TDD und Versionskontrolle.

Mein Chef möchte, dass ich ein Handbuch für Softwareentwickler schreibe, in dem die allgemeinen Prozesse, Protokolle, Tools und Richtlinien festgelegt sind, mit denen wir die Dinge erledigen. Mit anderen Worten, er möchte ein Buch "Dies ist, was wir hier tun", um es einem neuen Mitarbeiter zu erleichtern, sich mit unserer Arbeitsweise vertraut zu machen, und um meinem Chef zu helfen, zu verstehen, was seine Schergen tun und wie sie es tun es.

So wie ich das sehe, lege ich ein Fundament und es muss richtig gemacht werden. Wie würden Sie Themen für ein solches Handbuch auswählen? Können Sie einige Beispielthemen nennen?

Randnotiz: Wenn es darauf ankommt, sind wir in erster Linie ein Microsoft .NET-Shop. Wir beschäftigen uns mit agilen Methoden wie XP und Scrum, müssen sie jedoch möglicherweise stark modifizieren, damit sie in unserem Unternehmen funktionieren.

Phil
quelle
3
Ihr aktueller Prozess ist sehr schlecht. Haben Sie Unternehmensunterstützung, um Ihren aktuellen Prozess zu ändern, wird es nicht billig, die Art der Änderung, die erforderlich ist, wird Geld kosten. Es gibt viele Bücher zu diesem Thema, die meisten dieser Praktiken haben Werkzeuge, die erforderlich sind, um sie auf eine Weise zu implementieren, die keinen großen Aufwand erfordert.
Ramhound
einkaufen für handbuchthemen?
gnat
1
@gnat Guter Punkt. Siehe Bearbeiten.
Phil
Gute Bearbeitung (Sie sind anscheinend dem Link gefolgt). Ich würde auch ändern, welche Arten von Themen Ihrer Meinung nach wichtig sind ... zu etwas wie Wie würden Sie die Wichtigkeit der Themen einschätzen ... - auf diese Weise würde es besser zu Jeffs Anleitung passen, soweit ich es verstehe
gnat
1
Es geht mir nicht wirklich darum, wie man die Wichtigkeit der Themen einschätzt, da ich denke, dass ich das schon kann. Ich suche vielmehr nach Beispielen. Ich habe Antworten auf abstrakte Fragen immer als besser angesehen, wenn sie mit Beispielen versehen waren. Siehe Bearbeiten. Übrigens, ich schätze Ihre Hilfe, die meine Frage besser macht.
Phil

Antworten:

20

Ich würde es in Abschnitte wie zerbrechen

  • Aktuelle Mitarbeiter - Namen und Titel (idealerweise mit Fotos)
  • Bewerbungen, Logins bei ihnen, zu erfassende Daten und zu übermittelnde Erlaubnisanfragen
  • Lesezeichen für Unternehmenssites und wichtige externe Websites, die für das Unternehmen relevant sind
  • Anwendungen, die das Unternehmen für Kommunikation, E-Mail, Konferenzraumbuchung und Freigabebildschirm verwendet
  • Verfahren für unternehmensbezogene Aktivitäten wie Spesenabrechnungen, Buchung von Reisen
  • Developer Machine Setup. Beschreiben Sie den Prozess des Einrichtens einer neuen Entwicklermaschine im Detail. Dies wird normalerweise nur für einen Tag "erwartet", in der Realität dauert es jedoch häufig 3-5 Tage.
  • Der Entwicklungsprozess, wie die Arbeit verfolgt, zugewiesen und aktualisiert wird und welche Tools verwendet werden.
  • Wie man testet, was man testet, wann man testet, wo man testet.
  • Codierungsstandards, einschließlich Dateinamenskonventionen und sprachspezifischer Standards.
  • Wie man mit Fehlern umgeht, wo man sie dokumentiert, wie man sie behebt.
  • Bereitstellungsprozess, was sind die wichtigsten Dinge, die für Produktionsschübe zu wissen sind.
  • Wie zu dokumentieren, was zu dokumentieren, wann zu dokumentieren.
  • Wo Zeug ist, zB Ort (e) für Code, Daten, Standards, Dokumentation, Links und andere Assets.

Wenn Sie es modular gestalten, können Sie oder andere Teile auch separat aktualisieren. Beispielsweise ändern sich die Namen und Positionen der Mitarbeiter häufig, wenn Personen kommen und gehen.

Für jeden Abschnitt würde ich mich bemühen, ihn aus der Sicht eines Neulings zu schreiben. Am wichtigsten ist es, sicherzustellen, dass es für einen Neuling wirklich Sinn macht. Ihr Chef ist offensichtlich nicht die richtige Person, um dies zu überprüfen, da er nicht das beabsichtigte Publikum ist. Er hat das Recht, es zu wollen, aber stellen Sie sicher, dass der Inhalt nicht von ihm getestet wird . Auch ein "Neuling" hat beide nur "1 Woche" als Neuling ... und nur einen Standpunkt. Daher ist es wahrscheinlich (und wird empfohlen), dass das Dokument mit jedem neuen Mitarbeiter verfeinert wird. Tatsächlich ist es eine ziemlich gute Aufgabe, sie auch für ihre erste Woche zuzuweisen, dh "Update the newbie manual".

Für Agile / SCRUM:

Das Schwierigste an Agile und SCRUM ist, es wirklich zu tun.

Zum Lesen würde ich bei http://agilemanifesto.org/ anfangen und von dort aus gehen.

Ich würde auch das bekannte http://www.halfarsedagilemanifesto.org/ lesen, das die Tatsache verstärkt, dass man wirklich alle Aspekte berücksichtigen muss, damit es funktioniert. Wenn Sie Agile für Ihr Unternehmen stark modifizieren müssen, ist es wahrscheinlich, dass die Benutzer die Vorteile nutzen möchten - ohne die richtigen Prozesse zu verwenden. Diese Tatsache selbst sollte präsentiert werden, um jegliche Halbheit abzuwehren.

Michael Durrant
quelle
6
Mir gefällt, wie oft Sie dies bearbeiten. Wie ... beweglich von dir. :)
Phil
Wir möchten nicht unbedingt die agilen Prinzipien generell modifizieren. Wir würden nur bestimmte Praktiken wie XP modifizieren, da wir nicht wirklich die Arbeitskräfte haben, um alle erforderlichen Rollen zu implementieren. Das könnte eine andere Frage für einen anderen Tag sein.
Phil
Entschuldigung, ich habe die Antwort vorerst entfernt, da die Frage geändert wurde.
Phil
1
Bonuspunkte, wenn Sie ein Firmen-Wiki eingerichtet haben, in dem diese Informationen gespeichert sind ...
Spencer Rathbun
Hallo Spencer, das ist interessant. Ich habe auch gerade angefangen, ein Github-Wiki mit Markdown zu verwenden. Irgendwelche Gedanken darüber, wie sie vergleichen. Offensichtlich kennen viele Leute Github aus Code und Markdown aus SO, so dass es einfach ist, adoptiert zu werden.
Michael Durrant
4

Es hört sich so an, als müssten Sie einige Praktiken einführen, bevor Sie sie dokumentieren!

a) Quellcodeverwaltung - Wie speichern Sie Ihre Quellcodeverwaltung und wie führen Sie die Revisionskontrolle durch?

b) Versionsverwaltung und -verfolgung - Wie erstellt man eine Version, nummeriert sie und vergleicht einen aktuellen Versionskandidaten mit einer früheren Version

c) Problem Management - Wie können Sie Fehler in Ihren Releases nachverfolgen?

Dies sind ziemlich einfache Dinge, aber die Implementierung kann viel Zeit in Anspruch nehmen (und möglicherweise Geld kosten).

Scott C Wilson
quelle
2
+1, um es einfach zu halten und sich auf wichtige Themen zu konzentrieren. Wir brauchen wirklich keine "großen Regierungsmandate" für Codierungsstile.
kirk.burleson
3

Themen, die ich in ein Entwicklerhandbuch aufnehmen würde:

  • Rollen / Positionen innerhalb der Abteilung und deren Zuständigkeiten
  • Software-Anforderungen für Entwicklercomputer (dh erforderliche Entwicklungsumgebung)
  • Wo und wie Sie auf das Quellcode-Repository zugreifen
  • Verwendete Entwicklungswerkzeuge (zB IDE)
  • Codierungsstil / Standards
  • Dokumentationsstandards
  • Testprozess
  • Build-Prozess
  • Bereitstellungsprozess
  • Support- und Issue-Management-Prozess
  • Wo Sie die aktuellste Version dieses Handbuchs erhalten

Beachten Sie, dass dieses Handbuch nur entwicklungsspezifische Elemente und keine unternehmensweiten Informationen enthalten sollte (die in einem Mitarbeiterhandbuch enthalten sein sollten).

Bernard
quelle
2

Verwendung der Quellcodeverwaltung

  • Welches Quellcodeverwaltungs-Tool verwenden Sie?
  • Syntax allgemeiner Befehle / Tools in der IDE.
  • Verzweigungs- / Zusammenführungsstrategie.
  • Wie sollte die Einheit eines Commits sein? Wie lange ist es zu lang, um eine Datei auschecken / nicht festschreiben zu lassen?
  • Welchen Grad an "Doneness" bezeichnet ein Commit / Check-In? Kompiliert? Unit-Tests bestanden? Bewertet?
  • Was wird voraussichtlich in den Notizen für ein Commit / Check-in enthalten sein.
  • Rollback-Prozeduren.
JohnMcG
quelle