Falls ihr ein komplexes Produkt am Start habt, beispielsweise Amazon Web Services, dann schreibt bitte keine Romane oder schlecht querzulesende Texte um Trivialitäten eurer Schnittstellen und Datentypen zu beschreiben.
Gerade Aufstellungen von Konfigurationsoptionen und Datentypen wiederholen sich in ihrer Struktur millionenfach. Hierbei sollte ein einheitliches Format eingehalten werden, sodass beim „drüberfliegen“ wichtige Details wie Default-Einstellungen, Abhängigkeiten zu anderen Optionen klar werden – Beispielsweise eine Tabelle.
Ausserdem sollte ein plausibles, in sich logisches und realistisches Beispiel-Setup verwendet werden, dass keine Fehlinterpretationen zulässt.
Beispielwerte sollten beschreibend sein, sodass man deren Ursprung, Bedeutung und auch Abhängigkeiten nachvollziehen kann. Niemand mag die Hölle aus generische „application“ oder „data“-Ressourcen.
Ausserhalb des Nutzers definierte Vorgaben oder implizierte Rückfallebenen der Dienste müssen angesprochen und berücksichtigt werden (bspw: EC2 Classic VPC etc). Insbesondere, wenn sie global für den gesamten Account gelten, auch wenn man diesen partitionieren kann.
Beispiele sollten, je nach Komplexität, in verschiedene „Stufen“ unterteilt sein:
- Einfaches Beispiel mit unbedingt notwendigen Einstellungen und Diensten um die Anzahl an Variablen gering zu halten
- Komplexeres Beispiel z.B. zur Darstellung der Redundanzoptionen
- Varianten, die genannte Beispiele um Nice-to-Have oder Bonus-Features erweitern (Automatisches skalieren nach Mondkalender, Logrotation, Generierung von weiteren Umsätzen durch das verwenden weiterer kostenpflichtiger meinungsstarker Bikeshedding-Dienste)
Neben der „Referenz“ von Ressourcen, Datentypen, Methoden etc. muss auch das „big picture“ abgedeckt sein. Hier bieten sich einfache Checklisten an, statt entweder keine oder komplexe Visualisierungen (UML) anzubieten.
Checklisten sind in ernsthaften Branchen schon lange verbreitet und geschätzt. Sie sind kurz und bündig. Sie werden laufend optimiert um Zweideutigkeiten zu verhindern. Sie dienen einem klaren Zweck, einem klaren Ziel und sind somit relativ einfach zu überprüfen und zu aktualisieren. Sie sind einfach versionierbar, sowohl technisch (Versionsverwaltung) als auch den Nutzern gegenüber (Versionsnummer etc).
Ein Anti-Beispiel, wie man das alles falsch macht: Amazon CloudFormation.