Jeder von Selectel bereitgestellte Dienst kann in Ihrem persönlichen Konto - Control Panel - verwaltet werden . Viele unserer Produkte können auch über API-Anfragen gesteuert werden. Produktanweisungen und API-Dokumentation finden Sie in einer einzigen Hilfe .
Die Hauptidee des Hilfezentrums besteht darin, unseren Kunden die Möglichkeit zu geben, jederzeit unabhängig Antworten auf die meisten ihrer Fragen zu Selectel-Diensten zu finden.
Als nächstes werden wir darüber sprechen, wie wir den Ansatz zur Vorbereitung der Dokumentation geändert und das Erscheinungsbild der Wissensdatenbank aktualisiert haben.
Die technische Implementierung der Wissensbasis und ihrer visuellen Komponente vor drei Jahren deckte alle Anforderungen eines Nachschlagewerks mit Informationen vollständig ab. In der vergangenen Zeit stand das Unternehmen jedoch nicht still, sondern entwickelte sich aktiv weiter, indem es sowohl neue als auch bestehende Dienste einführte.
Vor etwa einem Jahr haben wir festgestellt, dass die vorhandene Online-Hilfe nicht den Anforderungen unserer Kunden entspricht:
- Das Navigationsmenü wuchs wie ein Obstbaum, der die Pflege eines Gärtners nicht kennt.
- Die Suche ist nicht mehr bequem.
- Das visuelle Design war nach und nach veraltet.
Bisher war die Dokumentation für die API unserer Produkte nicht öffentlich verfügbar - einige wurden im my.selectel.ru- Kontrollfeld veröffentlicht , einige wurden auf Anfrage herausgegeben und einige wurden vollständig in einem Textformat beschrieben, das auf dem neuesten Stand gehalten wurde sehr problematisch. Jetzt Kenntnisse über die Automatisierung der IT-Infrastruktur und die Interaktion mit dem Backend von Selectel-Diensten auf der Registerkarte API-Dokumentation .
Ein kleiner Ausflug in die Vergangenheit
Vor zehn oder fünfzehn Jahren konnten sich nur wenige Unternehmen, die in Russland Software herstellen, einer Online-Hilfe rühmen. Die Bedienungsanleitungen wurden im Word-Format in immer neuen Stilen verfasst und versuchten, die in den 70er Jahren des 20. Jahrhunderts erstellten GOSTs auf moderne und sich ständig ändernde Anforderungen anzuwenden.
Das Mem ist immer noch bei technischen Redakteuren beliebt:
Bis zum heutigen Tag gibt es Unternehmen, die sich bereits einer praktischen Site-Oberfläche rühmen können, deren Dokumentation jedoch auf der Ebene "Download-Anweisungen im PDF-Format für 45 Blatt" bleibt.
In großen Unternehmen ist die Wissensbasis stark mit technischem Support verbunden. In einer idealen kugelförmigen Welt im luftleeren Raum sollte der Benutzer in der Lage sein, 80% der Antworten auf seine Fragen unabhängig zu finden, ohne den technischen Support zu kontaktieren.
Das Portal mit Dokumentation bringt keinen offensichtlichen Gewinn, kann jedoch aufgrund des Skripts Zeit für den technischen Support sparen:
- Der Benutzer hat den Service bestellt.
- Konfrontiert mit nicht offensichtlichen Momenten beim Einrichten.
- Ich wollte den technischen Support kontaktieren.
- Ich ging zur Wissensbasis und fand die Informationen, die ich selbst brauchte.
- Ich habe den technischen Support nicht kontaktiert.
- Profitieren!)
Es gibt oft die Meinung, dass die Hilfeinformationen den Benutzern erst helfen, die Dienste zu verstehen, nachdem sie verbunden wurden. Dies war wahrscheinlich in den Tagen der Fall, als gedruckte Bücher mit Informationen zur Arbeit unter Windows veröffentlicht wurden. Jetzt wird es jedoch genauso wichtig, potenziellen Benutzern vor dem Kauf offen zu zeigen, wie der Dienst funktioniert.
Die meisten Softwareunternehmen entwickeln irgendwann APIs für den internen Gebrauch und für Kunden. Unternehmen teilen eine Reihe von Eingaben, indem sie öffentliche APIs veröffentlichen, damit Kunden ihre Dienste in die Produkte des Unternehmens integrieren können.
Viele benutzerdefinierte Aufgaben können automatisiert werden, einschließlich der Verwendung vorgefertigter Codestücke als Konstruktor, um die benutzerfreundlichste Infrastruktur zu erstellen. Code-Teile ohne Erklärungen darüber, was es ist, was es tut und wie es verwendet wird, sind jedoch von geringem Nutzen - Sie werden nicht brutal herausfinden müssen, welche Methoden es gibt und welche Daten sie voraussichtlich eingeben werden.
- Was muss getan werden, um die Verwendung der öffentlichen API angenehm zu gestalten?Als Dokumentation für die API geben sie normalerweise ein minimales Beispiel für die Interaktion an, das die Methoden (auch Endpunkte genannt) beschreibt und Antworten vom Dienst bereitstellt. Mithilfe der Kubernetes-API können Sie beispielsweise die Arbeit mit Clustern und Knoten in verwalteten Kubernetes automatisieren .
- Dokumentation beifügen!
Welche Aufgaben standen vor uns?
Unsere visuelle Lösung machte es nicht mehr einfach, die benötigten Artikel zu finden, und das vorhandene Menü wurde zu einem unlesbaren "Blatt". Unlesbare Dokumentation ist genauso schlecht wie irrelevante Texte. Die Leute sind es gewohnt, gut angelegte Materialien zu lesen. Blogs, soziale Netzwerke, Medien - alle Inhalte werden nicht nur schön präsentiert, sondern sind auch leicht zu lesen und angenehm für das Auge. Derzeit können die UX- und UI-Anforderungen nicht ignoriert werden, insbesondere bei einer derart großen Anzahl von Texten.
Bei der Entwicklung von Technologien für die visuelle Gestaltung von Websites haben wir festgestellt, dass das Erscheinungsbild unserer Wissensbasis veraltet ist. Die bloße Verwendung von Ankern und Listen in KB-Artikeln hat nicht geholfen. Es war notwendig, die gesamte Struktur der Dokumentation und des Suchmechanismus zu überarbeiten.
Häufige Probleme mit der Dokumentation
Im Allgemeinen abwesend oder niemand weiß von seiner Existenz. Eine
Anweisung, die nicht gefunden werden kann, ist nicht besser als eine Anweisung, die nicht existiert.
Wir haben dieses Problem folgendermaßen gelöst: Wir haben begonnen, Links zu nützlichen Artikeln in unsere monatliche Mailingliste aufzunehmen, Übergänge auf den Produktseiten der Website hinzuzufügen und Benachrichtigungen für alle interessierten Mitarbeiter des Unternehmens über einen speziellen Kanal im Corporate Messenger einzurichten.
Veraltet und nicht rechtzeitig aktualisiert
Der Dokumentationsprozess ist nicht in die Produktentwicklung integriert, die Dokumentation erfolgt auf Restbasis.
In unserem Fall hat der Produktmanager auch die Aufgabe, diese neue Funktionalität zu dokumentieren, während er an neuen Funktionen arbeitet.
Die Dokumentation ist komplex und schlecht organisiert. Es ist einfacher, den technischen Support zu fragen, wie das Problem gelöst werden kann. Das
Schreiben von Dokumentation zum Zwecke der Dokumentation ist sinnlos und sollte leicht zugänglich sein. Je mehr Optionen zum Auffinden eines Dokuments vorhanden sind, desto besser.
Wir haben das Design der Abschnitte unserer Wissensdatenbank komplett überarbeitet. In einigen Fällen funktionierten die universellen Vorlagen nicht. Daher mussten wir aktiv mit allen Beteiligten interagieren, sei es mit dem Produktmanager, dem technischen Support oder dem Front-End-Entwicklungsteam.
API-Dokumentation in den öffentlichen Raum verschieben
Eines der Probleme bei der Verwendung der in OpenAPI, Swagger oder einem anderen Generierungswerkzeug generierten API-Dokumentation ist die komplexe Integration mit dem Rest der Site. Benutzer müssen einfachen Zugriff auf alle Anweisungen und Artikel haben. Es ist unpraktisch, wenn Endpunkte in einer Ansicht angezeigt werden und Textbeschreibungen derselben Prozesse auf einer anderen Seite angezeigt werden.
Beibehalten eines einzelnen visuellen Bildes
Beim Erstellen eines einzelnen Hilfezentrums mussten wir eine konsistente Anzeige von Anweisungen und Spezifikationen mit einer Reihe von "git + markdown + swagger" beibehalten.
Wie es jetzt funktioniert
Technische Umsetzung
Die Wissensdatenbank wurde ursprünglich um eine Kombination aus Confluence und einem statischen Seitengenerator erstellt.
Wir haben Confluence fallen lassen und sind zu Documentation-as-Code übergegangen. Jetzt ist der gesamte Quellcode für die Wissensdatenbank im Markdown-Format gesetzt und im Git-Versionsspeichersystem gespeichert. Eine Knowledge Base-Site wird mithilfe des Hugo Static Site Generator aus dem Repository erstellt.
Die Site wird aus den Dateien generiert, die im Hauptzweig des Git-Repositorys enthalten sind. Daten können nur über eine Pull-Anfrage aktualisiert werden, mit der Sie alle neuen Abschnitte der Dokumentation überprüfen können, bevor sie öffentlich veröffentlicht werden. Ein solches System erleichtert auch den Ansatz, Änderungen vorzunehmen - Mitarbeiter des Unternehmens können jederzeit eine Niederlassung erstellen und alle erforderlichen Änderungen hinzufügen.
Mehr zur Dokumentation als Code
Das Prinzip "Dokumentation als Code" impliziert die Verwendung der gleichen Tools zum Schreiben von Dokumentation wie zum Erstellen von Code:
- Text-Markup-Sprachen;
- Versionskontrollsysteme;
- Code-Review.
Das Hauptziel dieses Ansatzes ist es, Bedingungen für die gemeinsame Arbeit des gesamten Teams am Endergebnis zu schaffen - eine umfassende Wissensbasis und Anweisungen für die Nutzung einzelner Produktdienstleistungen.
Arbeiten mit Swagger-Dateien
Selectel-Produktentwickler erstellen eine API und laden Kommentare im Swagger-Format in den Code hoch. Dies ist eine Textdatei im * .yaml-Format, die als Code verwendet werden kann. Wenn die API aktualisiert wird, wird auch die Swagger-Datei aktualisiert, was das Aktualisieren der Dokumentation erleichtert.
Die folgende technische Lösung wird für die API-Dokumentation verwendet:
- Git-Repository mit Swagger-Spezifikationsdateien im * .yaml-Format, gruppiert nach Produkt;
- Git-Repository mit Übersetzungen von Swagger-Spezifikationen im * .json-Format;
- Git-Repository mit Dateien im * .md-Format;
- Dateien im * .md-Format enthalten Textbeschreibungen und werden in spezielle Endpunktbeschreibungs-Tags eingeschlossen, die mit Dateien im * .json-Format aus dem Git-Repository abgerufen werden.
- Hugo statischer Site-Generator.
Zusätzlich zur Struktur des Repositorys wurden Regeln für die Arbeit damit entwickelt:
- Es wurde ein Styleguide erstellt - eine Checkliste für Swagger-Dateien, anhand derer Entwickler beim Aktualisieren der API-Spezifikationen prüfen.
- Der Hauptzweig des Git-Repositorys mit Dateien im Format * .md spiegelt den Status der aktuellen Spezifikationen wider und befindet sich de facto in der Produktion.
- Pull-Request an den Master-Zweig wird ausgeführt, wenn Updates für die Produktion freigegeben werden.
Visuelle Komponente
Der erste Schritt bestand darin, die Navigation zu überarbeiten und Regeln zu erstellen, nach denen die Abschnitte der Wissensbasis gebildet werden. Gemeinsam mit UX-Designern haben wir eine Informationsarchitektur erstellt. Die Struktur sollte so transparent wie möglich sein, damit der Leser nicht denkt: "Wo finden Sie diesen Artikel?" Zusammenfassend gibt es zwei Ansätze:
- Von der Schnittstelle. Der Inhalt dupliziert die Abschnitte des Panels (separat für Dienste). Dies war in der vorherigen Version der Wissensdatenbank der Fall.
- Aus Aufgaben. Die Titel von Artikeln und Abschnitten spiegeln die Aufgaben der Benutzer wider.
Um die Struktur zu rationalisieren, haben wir eine Kombination dieser beiden Ansätze verwendet. Selbst in neueren Versionen des Control Panels mit einer durchdachten Benutzeroberfläche und Benutzeroberfläche müssen zumindest die Begriffe erläutert werden, da unsere Produkte technisch komplex sind und die Benutzer sehr unterschiedlich sind.
Zusätzlich zur Aktualisierung des Inhaltsverzeichnisses haben wir die Suche und die Breadcrumbs verbessert. "Brotkrumen" ist der Pfad des Benutzers zur aktuellen Seite mit der Möglichkeit, zu einer beliebigen Ebene zurückzukehren. In der vorherigen Version der Wissensdatenbank war es unmöglich, in das Inhaltsverzeichnis zu gelangen, und es war unpraktisch. In der neuen Version haben wir dies behoben.
Jedes Unternehmen erstellt API-Dokumentationen gemäß seiner eigenen Vision von Stil, Struktur und Sinn für Schönheit. Wenn wir 4-5 öffentliche APIs verschiedener Unternehmen öffnen, können wir natürlich einige Gemeinsamkeiten feststellen: Struktur, umfangreiche Codebeispiele und Syntaxhervorhebung, lange Seiten. Trotzdem haben alle Beispiele Besonderheiten. Beispielsweise ist die Lokalisierung von Endpunktbeschreibungen selten, während die Struktur von Endpunktbeschreibungen meistens gleich aussieht.
Verschiedene Empfehlungen zur Strukturierung der API-Dokumentation:
Gruppieren von Endpunkten
Neben der Bereitstellung von Informationen für jeden Endpunkt ist es bei vielen Endpunkten ratsam, diese zu gruppieren. Die lange fortlaufende Liste der Endpunkte erschwert die Navigation.
Separate Beschreibung der Methoden
Bei gleichzeitiger Verwendung der GET / POST-Methoden sollte nur eine Methode in einer Zeile beschrieben werden.
Das heißt, die erste Zeile ist in diesem Fall die Beschreibung von GET, die zweite Zeile ist die Beschreibung von POST, sodass Sie Verwirrung vermeiden können.
Automatisierung von Änderungen
Vereinfachen Sie das Vornehmen von Änderungen, ohne jeden Abschnitt manuell neu zu formatieren. In unserem Fall übersetzen wir nur den Text der Swagger-Datei, ohne das Markup zu berühren, dank der Automatisierung dieses Prozesses, die unsere Entwicklerspezialisten konfiguriert haben.
Hervorheben der Syntax
Entwickler lieben Codebeispiele am meisten auf der Welt. Kein Entwickler wird sich darüber beschweren, dass es zu viele Beispiele gibt - sie verkürzen die Zeit zum Eintauchen in das Produkt erheblich.
Das Arbeiten mit Codeteilen ist viel praktischer, wenn je nach Programmiersprache unterschiedliche Elemente entsprechend gefärbt sind.
Da die Standard-Code-Hervorhebung nur für dunkle Hintergründe verfügbar war, hat der Frontend-Entwickler diese Lösung mithilfe von Highlight.js an unseren Unternehmensstil angepasst.
Anstelle einer Schlussfolgerung
Die aktualisierte Wissensdatenbank steht den Benutzern seit März zur Verfügung, und die API-Dokumentation ist seit Anfang August verfügbar.
„- Wenn Sie lange laufen, befinden Sie sich bei uns sicherlich an einem anderen Ort.Was wir bereits getan haben, ist nur ein weiterer Schritt zur Verbesserung der Wissensbasis. Wir werden den APIs unserer anderen Dienste schrittweise neue Anweisungen und Dokumentationen hinzufügen.
"Nun, hier, weißt du, musst du so schnell rennen, um am selben Ort zu bleiben, und um an einen anderen Ort zu gelangen, musst du doppelt so schnell rennen."
(Lewis Carroll "Alice durch den Spiegel")