Wie wir die Dokumentation neben dem Code aufbewahren / Sudo Null IT News

Bei der Alfa-Bank bewahren wir die Dokumentation seit mehr als 5 Jahren neben dem Code auf. Diese Praxis wird jedoch nicht überall angewendet. Tatsache ist, dass unsere Dokumentation in Schichten unterteilt ist: Vorderseite, Mitte und Rückseite. Wenn mit der Mitte alles in Ordnung ist – einer Schicht von Microservices -, dann gibt es bei der Vorder- und Rückseitendokumentation eine Schwierigkeit, die mit der Notwendigkeit verbunden ist, Binärdateien, Bilder mit Beispielen für Benutzeroberflächen zu speichern.

In dem Artikel werde ich beschreiben, wie wir mit der Middle-Dokumentation arbeiten, und am Beispiel der Frontend-Dokumentation die bestehenden Schwierigkeiten mit Binärdateien skizzieren und Ihnen sagen, welche Lösungen wir in Betracht ziehen. Der Artikel richtet sich an Technische Redakteure, Systemanalysten und alle, die an der Erstellung technischer Dokumentationen für Softwareprodukte beteiligt sind.

Kurz darüber, wie wir die Dokumentation pflegen

Dokumentation ist ein integraler Bestandteil eines Softwareprodukts. Um die Konsistenz seiner Teile zu gewährleisten, möchte ich mit gängigen Werkzeugen daran arbeiten. In diesem Fall ist die Wahrscheinlichkeit, dass der Code nicht mit der Dokumentation übereinstimmt, geringer als in dem Fall, wenn der Code in einem System und die Dokumentation in einem anderen gepflegt wird. Vor allem, wenn der Code und die Dokumentation von verschiedenen Personen geschrieben und überprüft werden.

Unsere Projektdokumentation ist in Schichten unterteilt: Vorderseite, Mitte und Rückseite. Und je nach Schicht führen wir sie an unterschiedlichen Orten durch.

Mitte. Neben dem Code befindet sich die Dokumentation für die mittlere Schicht oder Microservices-Schicht. Wir verwenden Bitbucket als unser Versionskontrollsystem. Wir verwenden Textauszeichnungssprache, um Dokumente zu entwickeln AsciiDoc in Verbindung mit PflanzeUMLmit dem Sie Diagramme aus Text erstellen können.

Vorderseite. Wir könnten auch die Dokumentation für die Vorderseite neben dem Code aufbewahren, aber es erfordert Bilder mit Beispielen für die Benutzeroberfläche – Binärdateien. Und sie sind ziemlich schwer im Vergleich zu Textdateien mit Quellcode. Speichert man sie in Bitbucket, dann schwillt das Repository schnell an und beim Datenaustausch zwischen lokalen Maschinen und dem Server steigt die Belastung des Netzwerks stark an. Daher pflegen wir die Dokumentation für die Front in Confluence.

Backend. Mit Backend meine ich in erster Linie unser ABS Equation (Anmerkung: Equation ist ein komplexes, mehrwährungs- und mehrsprachiges System für Banken). Historisch gesehen sind die Dokumentation dafür die Spezifikationen in MS Word und MS Excel, die in den Lotus Notes-Datenbanken platziert sind. Im Laufe der Zeit migrierten sie zu Confluence.

Hintergrunddokumentation kann an Bitbucket übertragen werden. Aber die ABS-Module haben eine eigene Benutzeroberfläche, sodass bei der Migration der Dokumentation auch das Problem der Speicherung von Binärdateien auftaucht, das wir noch nicht gelöst haben.

Gesamt. Die Dokumentation für die Mitte halten wir neben dem Code, für Vorder- und Rückseite – in Confluence.

Das Hauptproblem bei der Migration der Vorder- und Rückseitendokumentation zu Bitbucket ist die Notwendigkeit, Binärdateien mit Beispielen für die Benutzeroberfläche zu speichern. Das Problem ist, dass alles viel wiegt.

Im Folgenden werde ich beschreiben, wie wir mit der mittleren Dokumentation arbeiten. Und dann werde ich die Option in Betracht ziehen, was wir mit der Vorder- und Rückseite machen können, wie wir das Problem mit den Binärdateien hier lösen können.

Erfahren Sie mehr darüber, wie wir die Dokumentation auf der mittleren Schicht pflegen

Der mittlere Dokumentationsprozess sieht folgendermaßen aus:

  • Es gibt ein Projekt in Bitbucket. Das Projekt enthält Repositories mit dem Quellcode von Microservices.

  • Quelldateien sind in Ordner unterteilt. Einer der Ordner enthält Dokumentationsdateien für Microservices.

  • Mitglieder des Entwicklungsteams checken Repositories mit Quellcode und Dokumentation auf ihren lokalen Rechnern mit Git aus.

  • Sie nehmen Änderungen vor und senden sie zur Überprüfung an den Bitbucket-Server.

  • Nach erfolgreicher Überprüfung führen wir die Änderungen in den Master-Branch ein.

  • Das CI/CD-System erfährt von Änderungen im Master, entlädt die Quellen und führt sie durch eine vorkonfigurierte Pipeline. Ich gebe kein bestimmtes System an – in meiner Erinnerung gab es mehrere davon: Zuerst verwendeten sie Jenkins, dann testeten sie GoCD, dann wechselten sie zu Bamboo. Jetzt bewegen wir uns zu unserer eigenen Lösung, unter deren Haube sich derselbe Jenkins dreht.

  • Die resultierenden Builds von Code und Dokumentation werden von Artifactory gehostet. Die Dokumentation wird in Form von HTML-Dateien präsentiert.

Um zu verstehen, was der Quellcode und die gesammelte Dokumentation sind, werde ich ein Beispiel geben. Angenommen, wir haben einen Dienst, der eine getReport-Methode bereitstellt. Die Methode ermöglicht es Ihnen, einen Bericht über einen Kunden zu einem bestimmten Datum zu erhalten.

Die folgende Dateistruktur kann verwendet werden, um einen Dienst zu beschreiben:

index.adoc index.adoc getReport/getReport.adocgetReport/getReport.adocgetReport/getReport.pumlgetReport/getReport.puml

Die Mitglieder des Entwicklungsteams arbeiten lokal mit diesen Dateien. Offensichtlich sind die Inhalte der Dateien nicht sehr visuell, da sie Textauszeichnungen enthalten. Ich möchte das ausgefüllte Dokument sehen.

Das Ergebnis ist in der IntelliJ IDEA-Oberfläche mit installierten Plugins zu sehen AsciiDoc und PlantUML-Integration. Die Dokumentation kann auch vor Ort gesammelt werden.

Notiz. Für die Montage zu Bildungszwecken können Sie den Motor verwenden Arzt mit Verlängerung Asciidoctor PlantUml. Als PlantUML Server verwenden wir https://www.plantuml.com.

Beispiel für einen Build-Befehl:

PLANTUML_URL=” \ PLANTUML_ENCODING=”deflate” \ asciidoctor -r asciidoctor-plantuml index.adoc getReport/getReport.adoc

Als Ergebnis seiner Ausführung werden zwei Dateien erstellt – index.html

index.htmlindex.html

und getReport/getReport.html.

getReport/getReport.htmlgetReport/getReport.html

Im zusammengebauten Zustand ist die Dokumentation übersichtlich. Es hat Links, Tabellen, Diagramme usw. Und es scheint, dass der Rest der Dokumentation auch neben dem Code aufbewahrt werden sollte. Aber was tun mit Binärdateien?

Das Hauptproblem beim Speichern von Binärdateien neben dem Code ist ihre Größe.

Wir müssen einen alternativen Weg finden, diese Dateien zu speichern. Kann hier helfen Git-LFS. Wir belassen Bitbucket als Repository für Dokumentationsquellen und werden Bilder mit Beispielen für Benutzeroberflächen in Artifactory zum GitLfs-Repository hinzufügen.

Anhand der Dokumentation für die Front als Beispiel werde ich zeigen, wie Git LFS hilft.

Wie verwalten wir die Dokumentation für die Front?

Der Front-End-Dokumentationsprozess sieht folgendermaßen aus:

  • Analog zu Microservice-Repositories erscheint in den Repositories mit dem Quellcode von Frontend-Anwendungen ein Ordner zur Pflege von Dokumentationsdateien.

  • Für Binärdateien mit Beispielen für die Benutzeroberfläche können Sie darin einen separaten Unterordner erstellen, die Dokumente, aus denen Git LFS nachverfolgt.

  • Mitglieder des Entwicklungsteams checken Repositories mit Quellcode und Links zu Dokumentationsdateien auf ihren lokalen Rechnern mit Git aus. Wenn Sie die referenzierten Dokumentationsdateien selbst benötigen, verwenden Sie Git LFS.

  • Nach Änderungen werden die Binärdateien mit Beispielen für die Benutzeroberfläche in Artifactory gespeichert, und der Quellcode mit Links zu ihnen wird zur Überprüfung an den Bitbucket-Server gesendet.

  • Da Es gibt keine Binärdateien in Bitbucket, dann sollte die Beispielüberprüfung der Benutzeroberfläche entweder ignoriert oder Änderungen hochgeladen und die Dokumentation lokal gesammelt werden.

  • Nach erfolgreichem Review führen wir wie zuvor die Änderungen in den Masterbranch ein.

  • Das CI/CD-System muss lernen, während des Build-Prozesses Binärdateien von Artifactory zu erhalten. Der Rest der Pipeline bleibt unverändert.

  • Die resultierenden Code- und Dokumentations-Builds werden wie zuvor von Artifactory gehostet. Es ist wichtig, hier zu beachten, dass die Binärdateien für die HTML-kompilierte Dokumentation Teil des Builds sind. Daher werden sie in der Artifactory neu gehostet, was zusätzliche Ressourcen auf dem Server erfordert.

Ich werde an einem Beispiel zeigen, wie die Zusammenstellung einer Dokumentation, die einen Screenshot der Benutzeroberfläche enthält, funktioniert. Angenommen, wir haben eine Benutzeroberfläche, die einen Kundenbericht für ein bestimmtes Datum anzeigt. Zur Beschreibung dieser Schnittstelle kann folgende Dokumentenstruktur verwendet werden:

index.adocindex.adoc

  • Bilder – Ordner mit Screenshots;

  • images/index.png – ein Screenshot der Benutzeroberfläche, in der der Bericht angezeigt wird.

Quelle: https://vc.ru/alfabank/94450-115-fz-prostymi-slovami-pochemu-banki-blokiruyut-karty-i-internet-bank-i-chto-delat-esli-eto-proizoshloQuelle: https://vc.ru/alfabank/94450-115-fz-prostymi-slovami-pochemu-banki-blokiruyut-karty-i-internet-bank-i-chto-delat-esli-eto-proizoshlo

Nach dem Zusammenbau erhalten wir eine index.html-Datei, die inkl. ein Beispiel für eine Benutzeroberfläche, die einen Bericht über einen Client für ein bestimmtes Datum anzeigt.

So sieht index.html nach dem Zusammenbau aus.

index.htmlindex.html

So kann die Vorder- und Rückseitendokumentation neben dem Code aufbewahrt werden, auch wenn es Binärdateien mit Beispielen für die Benutzeroberfläche gibt. Diese Lösung wurde auf meinem lokalen Computer mit Testversionen von Bitbucket und Artifactory getestet. Darüber hinaus ist ein Pilotprojekt für die Infrastruktur der Bank geplant, bei dem Banksysteme und Daten aus realen Projekten verwendet werden.

Ergebnis

Die Praxis, die Dokumentation neben dem Code in der Alfa-Bank zu führen, besteht seit mehreren Jahren. Es hat jedoch noch keine allgemeine Anwendung gefunden. Die Gründe dafür sind unterschiedlich – von einer erhöhten Eintrittsschwelle für Spezialisten, die Dokumentation entwickeln, bis hin zur Unvollkommenheit von Technologien. Wir hören hier jedoch nicht auf, wir suchen, recherchieren und implementieren weiterhin Best Practices, wie im Beispiel der Frontdokumentation.

Wenn Sie die Dokumentation neben dem Code aufbewahren und auf das oben beschriebene Problem beim Speichern von Binärdateien (mit Beispielen für die Benutzeroberfläche) oder andere Probleme gestoßen sind, freuen wir uns, wenn Sie Ihre Erfahrungen in den Kommentaren teilen.

Similar Posts

Leave a Reply

Your email address will not be published.