Der Titel sagt wirklich alles.
Es kann manchmal vorkommen, dass Entwicklung und IT bei solchen Dingen im Streit sind. Welchen Dokumentationsgrad erwarten Sie, wenn Sie eine Lösung installieren, patchen, warten, starten, stoppen und diagnostizieren sollen, die auf einem oder mehreren Servern ausgeführt wird?
Antworten:
All diese Dinge sollten detailliert dokumentiert werden. Wenn der Vorgang jedoch Standard für das Betriebssystem, den Anwendungsserver, den Webserver usw. ist, können Sie davon ausgehen, dass die IT-Mitarbeiter wissen, wie das geht.
Installation: Dokumentieren Sie alles darüber, wie es installiert und konfiguriert ist, einschließlich der Feststellung, ob es ordnungsgemäß funktioniert.
Erzählen Sie uns von der Architektur, insbesondere von der Kommunikation zwischen verschiedenen Lösungskomponenten (z. B. Bereich von Ports - RPC-Mechaniker verwenden häufig einen Bereich von Ports - wir müssen wissen, wie groß der Bereich ist und wann der Anwendung möglicherweise die Ports ausgehen).
Patchen: Dokumentieren Sie alles, was für die Anwendung spezifisch ist - was vor dem Patchen heruntergefahren werden muss und alle Folgeaktionen nach dem Patchen (Caches, Indizes, Proxys, die möglicherweise gelöscht oder neu erstellt werden müssen).
Wartung: Dokumentieren Sie, wie normaler und abnormaler Betrieb aussieht - welche Warteschlangen und andere Dinge überwacht werden sollten und wie normal diese sind.
Erklären Sie uns, wie die Daten verwaltet werden - insbesondere Tabellen und Dateien, die unbegrenzt wachsen (z. B. Protokolldateien und Transaktionsverläufe). Wie sollen diese gelöscht werden und wie wirkt sich das Entfernen alter Einträge aus? (zur Berichterstattung usw.).
Erklären Sie uns, wie Sie standardmäßige "Business as usual" / In-Life-Management-Aktionen ausführen. Dies kann beispielsweise das Hinzufügen oder Ändern von Benutzerkonten sein.
Informieren Sie uns über weitere reguläre Verwaltungsmaßnahmen, die möglicherweise erforderlich sind (z. B. welche Zertifikate verwendet werden und was zu tun ist, wenn sie ablaufen).
Sagen Sie uns für alle Änderungen, wie Sie sie zurücksetzen sollen (nicht alle Änderungen sind erfolgreich). Und sagen Sie uns, dass Sie die Rollback-Pläne getestet haben!
Diagnose: Dokumentprotokolldateiformate und -speicherorte sowie JEDE Anwendungsfehlermeldung, die möglicherweise angezeigt wird, mit der Angabe, was die Fehlermeldung bedeutet, dass ein Fehler aufgetreten ist und was möglicherweise geändert werden muss, um das Problem zu beheben. Verwenden Sie niemals dieselbe Fehlermeldung für zwei verschiedene Ereignisse.
Abgeschossen und gestartet: Wie, in welcher Reihenfolge, spezielle Verfahren (z. B. Server vor dem Herunterfahren Verbindungen abbauen lassen).
Ich bin nicht der Meinung, dass der beste Weg, dies zu tun, darin besteht, die Anwendung über den Zaun zu werfen und die IT-Mitarbeiter herausfinden zu lassen, was benötigt wird. Die Betriebsdokumentation (und im Allgemeinen die Verwaltbarkeitsfunktionen der Anwendung) müssen im Voraus bedacht werden.
Eine weitere Frage wäre: Was passiert, wenn (nicht wenn) die Entwickler keine ausreichende Dokumentation bereitstellen?
Ich empfehle der IT, die Möglichkeit zu haben, Fehlerberichte für die Software einzugeben, wobei jedes von den Entwicklern verwendete Fehlerverfolgungssystem verwendet wird. Auf diese Weise können Sie einen Fehler eingeben, der besagt, dass die Anwendung die Festplatte mit Protokolldateien füllt, wenn sie Ihnen beispielsweise nicht mitteilen, dass die Dateien in einem bestimmten Ordner gelöscht werden müssen und dass nur eine Woche aufbewahrt werden soll "und schlagen vor, dass sie mit der IT an einer dokumentierten Technik zum Löschen dieses Ordners arbeiten.
Meine Liste der Anforderungen an die Dokumentation wäre (nicht in einer bestimmten Reihenfolge):
(Dokumentation zu :)
Dokumentation wie diese sind Beispiele für eine gute Dokumentation:
Ich würde eine Dokumentation wie diese als fehlerhaft betrachten:
Auch das FreeBSD-Handbuch ist ein hervorragendes Beispiel für die Dokumentation und den Ansatz von OpenBSD. Sie werfen Sachen raus, die nicht richtig dokumentiert sind.
EDIT: Diese Liste ist keineswegs vollständig, es sind nur die grundlegenden Dinge , die mir sofort in den Sinn kamen. Auch die Dokumentation sollte gut lesbar sein, nicht nur etwas, das sich liest, als hätte sich jemand übergeben .
Kurz gesagt, ich erwarte die Dokumentation, die ich spezifiziere und für die ich einen Vertrag abgeschlossen habe.
Zu oft wird dieses kritische Detail in einer Vereinbarung nicht berücksichtigt. Der Endbenutzer erwartet es und möchte es natürlich kostenlos. Gute Entwickler werden dieses Versehen frühzeitig korrigieren und Erwartungen festlegen, einschließlich Preis- und Zeitbedarf.
Ich glaube, die IT muss mit den Entwicklern kommunizieren, welche Art von Dokumentation benötigt wird. Der beste Weg, dies zu tun, ist, wenn die Entwicklung Vorabversionen (oder Iterationsversionen) einer Lösung liefert, mit der die IT spielen und testen kann, damit die IT mit den erforderlichen Antworten reagieren kann.
Das Erstellen angemessener Versionshinweise mit einer Anwendung wäre ein guter Anfang. Wenn sich mit der Version Änderungen am aktuellen Verhalten ergeben, Hinweise aus der Qualitätssicherung zu Änderungen an Abhängigkeiten oder Start / Stopp-Verhalten, Änderungen der Auslastung abhängiger Server oder Datenbanken usw.
@Spoike (Ich kann die Antworten noch nicht kommentieren ..)
IT-Implementierer (die Rolle variiert je nach Unternehmenstyp und -größe) müssen konsequent arbeiten, um Folgendes zu erreichen:
Mindestanforderungen für Installation / Umsatz - Mit anderen Worten, die IT kann nicht passiv sein und von Entwicklern erwarten, dass sie "wissen", welche Informationen zum Zeitpunkt der Installation / des Umsatzes benötigt werden. Ich habe festgestellt, dass es in der IT häufig erhebliche Verwirrung / Uneinigkeit darüber gibt, was eine ordnungsgemäße Dokumentation einer App ausmacht. Dev versteht die Anforderungen (wir hoffen) und die IT muss sich zusammenfinden, um herauszufinden, was - zumindest - erforderlich ist.
Ein Installations- / Umsatzverfahren - in Unternehmenseinstellungen können Sie dies als Änderungskontrolle oder Governance bezeichnen. Es handelt sich jedoch im Wesentlichen um einen Standardüberprüfungszyklus, bei dem sich die IT mit Dev PRIOR top install zusammensetzt, um eine Einweisung in das Produkt und seine Anforderungen zu erhalten.
Das Installieren einer App ist nicht anders als das Debüt einer Theaterproduktion. Bevor der Vorhang aufgeht, trifft sich der Regisseur (Hauptentwickler) wiederholt mit dem Bühnenproduktionsteam (IT-Implementierer), um sicherzustellen, dass für den Eröffnungsabend (die öffentliche Installation) alles "nur so" ist.
Sie können die Dev-Persona nicht ändern (warum sollten Sie das wollen?), Aber Sie können auf Ihr gemeinsames Ziel einer fantastischen App verweisen, die für alle Benutzer unglaublich schnell läuft. Ihre konsensfähigen IT-Dokumentanforderungen sind nur eines der Dinge, die erforderlich sind, um dies sicherzustellen.