Ich verbringe viel Zeit damit, Dokumentation zu lesen, und mir ist über die Jahre etwas aufgefallen.
Zwei Projekte können dieselbe Idee auf völlig unterschiedliche Weise beschreiben. Das eine gibt dir eine Liste von Funktionen. Das andere zeigt dir, wie diese Funktionen miteinander verbunden sind.
Ich erinnere mich normalerweise an die zweite.
Das passierte, während ich die Zahlungsarchitektur des Newton-Protocols durchlas.
Anfangs wollte ich gar nicht versuchen, den Workflow zu studieren. Ich wollte nur eine allgemeine Vorstellung davon, wie eine Zahlung durch das System gelangt. Nach ein paar Minuten fand ich mich dabei, den Weg vom Anfang nachzuverfolgen, statt direkt zum Transfer zu springen.
Die Anfrage kommt zuerst.
Danach durchläuft der Workflow die Policy-Übersicht und eine Attestation, bevor der Payment-Contract entscheidet, ob die Übertragung fortgesetzt wird. Das Betrachten der Sequenz hat mir geholfen zu verstehen, warum diese Bausteine im Diagramm auftauchen, statt sie als unabhängige Funktionen zu behandeln.
Noch etwas, das mir aufgefallen ist, war der Hinweis, dass kein Off-Chain-Server auf dem kritischen Pfad sitzt. Ich habe diesen Satz gelesen, zurück ins Diagramm geschaut und die Pfeile erneut verfolgt. Das Lesen des Textes und das Anschauen des Workflows zusammen ergab viel mehr Sinn, als wenn man das jeweils für sich allein gemacht hätte.
Ich denke, das ist etwas, das gute technische Dokumentation richtig gut macht.
Es gibt dir genug Informationen, um deine eigene Vorstellungskraft wieder zu überprüfen.
Ich habe das am Ende mehrmals gemacht.
Ich würde eine kurze Beschreibung lesen, mir das Diagramm ansehen und dann wieder zur Beschreibung zurückgehen. Jeder Durchgang beantwortete eine Frage, die ich zuvor nicht bemerkt hatte.
Wahrscheinlich deshalb mag ich Architekturseiten mehr als Ankündigungsbeiträge.
Ankündigungen sagen mir normalerweise, was sich geändert hat.
Architekturdiagramme helfen mir zu verstehen, wie die verschiedenen Teile eines Protokolls voraussichtlich zusammenarbeiten.
Als ich diesen Abschnitt der Dokumentation des Newton Protocols fertig gelesen hatte, blieb ich nicht mit dem Gedanken an nur eine einzelne Funktion zurück.
Ich habe darüber nachgedacht, den Workflow als Ganzes zu betrachten.
Für mich ist das normalerweise ein gutes Zeichen dafür, dass die Dokumentation ihren Job gemacht hat. $NEWT #newt @NewtonProtocol
