Snyk-Dokumentation: Unser bisheriger Weg

Seit drei Jahren verantworte ich die Snyk-Benutzerdokumentation und habe viele Verbesserungen an unseren Benutzerhandbüchern begleitet.

Eine Kultur des Mitwirkens

Wir haben eine einzigartige Kultur des Mitwirkens an unseren Benutzerhandbüchern geschaffen. Hunderte aktive Mitwirkende bei Snyk erstellen, aktualisieren und verbessern kontinuierlich die Inhalte unserer Dokumentation.

Einer der wichtigsten Schritte dabei war die Einführung eines Docs-as-Code-Prozesses in unserem Dokumentationsteam.

Docs-as-Code

Ein „Docs-as-Code“-Prozess bedeutet ganz einfach, dass der Schreibprozess dem Code-Entwicklungsprozess ähnelt und in der Regel entwicklerfreundliche Plattformen und Tools nutzt. Die Snyk-Dokumentation wird beispielsweise auf der GitBook-Plattform erstellt. Sie nutzt Git-ähnliche Änderungsprozesse, bietet eine einfache Bearbeitungsoberfläche und synchronisiert sich mit einem GitHub-Repository, in dem die Inhalte als Markdown-Dateien gespeichert sind. 

Dieser Prozess hat Beiträge für alle ermöglicht. Da die steile Lernkurve und Zugangsbeschränkungen professioneller Autoren-Tools wegfallen, können mehr Menschen an den Inhalten mitarbeiten – ohne prohibitive Lizenzkosten.

So erstellt Snyk Dokumentation 

Bei Snyk verfassen unsere Entwicklungsteams den ersten Entwurf der Dokumentation zu einer neuen Funktion direkt in der GitBook-Schreibumgebung. So übernehmen sie Verantwortung und bringen sich ein. Sie können Inhalte schnell beitragen, ohne sie manuell aus anderen Quellen zu übertragen und neu zu formatieren. Beginnt die Dokumentationsarbeit, bevor Funktionen in die Testphase gehen, ist die Dokumentation häufig bereits fertig und veröffentlicht, wenn die Funktion in die Closed-Beta-Phase eintritt. So erhalten unsere Nutzer schnell und einfach Zugriff auf die Informationen.

Wir schulen, unterstützen und ermutigen alle Mitwirkenden. Dazu gehört Hilfe direkt beim Bearbeiten mit dem Tool Grammarly ebenso wie die Standardisierung aller Reviews und Änderungen. Jedes neue Mitglied eines F&E-Teams erhält gezielte Anleitung und zugewiesene Autoren, damit klar ist, wie es Beiträge leisten und um Hilfe bitten kann. Frühzeitige Unterstützung und Automatisierung sind entscheidend, damit die Dokumentation mitwachsen kann – deshalb spielen sie in Snyks Ansatz eine wichtige Rolle.

Kurz gesagt, verfolgt Snyk zwei Ansätze:

• Shift Left: Testen Sie Ihren Code früher – während Sie ihn schreiben und nicht erst kurz vor der Veröffentlichung.

• Shift Down: Lassen Sie Entwickler die Tests durchführen, statt spezialisierte Sicherheitsteams damit zu beauftragen. 

Unsere Dokumentationsprozesse folgen demselben Modell. Zusammenarbeit, Skalierbarkeit und Automatisierung liegen in unserer DNA.

Erfolge unserer Mitwirkungskultur

Durch die grundlegende Veränderung, wie Snyk Dokumentation erstellt, haben wir Anfang 2024 mehr als 250 aktive Mitwirkende. In den vergangenen zwei Jahren haben wir außerdem über 6.000 Änderungen und Verbesserungen an unserer Dokumentation vorgenommen – fast zehn pro Tag.

Die Mitarbeitenden engagieren sich und bringen sich ein. Technische Redakteure gelten zu Recht als Wegbereiter für Funktionen und nicht als Hindernisse. Wir konnten Last-Minute-Aktionen zum Dokumentieren neuer Funktionen vermeiden, die entweder die Veröffentlichung verzögern oder zu minderwertiger Dokumentation führen – oder beides.

Woran wir arbeiten: Nutzererfahrungen, Nutzertypen und klare Empfehlungen

Wir konzentrieren uns jetzt darauf, die Qualität unserer Dokumentation zu verbessern, sie an den Nutzererfahrungen und Nutzertypen bei Snyk auszurichten und mehr Inhalte mit klaren Empfehlungen bereitzustellen.

Dokumentation passend zu Nutzererfahrungen

Wir gestalten derzeit die Informationsarchitektur unserer Dokumentation neu. Schon immer haben wir klare, beschreibende Dokumentation dazu bereitgestellt, wie Nutzer Snyk-Produkte verwenden. An konkreten Empfehlungen für bewährte Vorgehensweisen oder ausführlichen Beispielen mangelte es jedoch. Ohne solche Leitlinien mussten unsere Nutzer ihren eigenen Weg zur Implementierung finden, denn die Struktur der Dokumentation entsprach nicht ihren Erfahrungen, Abläufen und Personas. 

Ausgangspunkt

Hier sehen Sie unsere Struktur von 2022, die nach Snyk-Produkten gegliedert war:

Den Weg beschreiben

Inzwischen haben wir eine vereinfachte, zielgerichtete Informationsarchitektur, die den linearen Erfahrungen der Nutzer entspricht:

Unser Inhaltsangebot umfasst:

• Einstiegsbereiche, die den ersten Teil der Nutzererfahrung („Onboarding“) beschreiben. Dazu gehören ein Quickstart zur Evaluierung von Funktionen und ein Abschnitt Implement Snyk für die übergeordnete Planung der geschäftlichen Implementierung.

• Anschließend beschreiben wir die Details der Integrationen mit Snyk. Dazu gehören zunächst Git-Integrationen, um Ihre Repositories für die Quellcodeverwaltung mit Snyk zu verknüpfen, und CI/CD-Integrationen für längerfristige Bereitstellungsstrategien.

• Danach geht es um den täglichen Betrieb und das Scannen mit Snyk, einschließlich der Verwendung der einzelnen Snyk-Produkte, wie etwa Snyk Open Source.

• Im Abschnitt Snyk Admin beschreiben wir allgemeine Verwaltungsaufgaben.

• Abschließend stellen wir zwei eigenständige Bereiche vor: CLI und API.

Dokumentation passend zu Nutzertypen 

Wir haben mehrere Gruppen von Snyk-Nutzern festgestellt, die häufig auf unsere Dokumentation zugreifen: Entwickler, Administratoren und Implementierungsverantwortliche sowie Application-Security-Mitarbeitende. 

Jeder Nutzertyp benötigt andere Informationen. Deshalb möchten wir sicherstellen, dass alle Personas einfach auf die Dokumentation zugreifen und darin navigieren können – und genau die relevanten Inhalte finden.

Zum Beispiel:

• Entwickler: Wir bieten Inhalte zu Quickstart und Scannen mit Snyk.

• Administratoren und Implementierungsverantwortliche: Sie können sich auf Enterprise-Konfiguration und Snyk Admin konzentrieren.

• Application Security: Hier liegt der Schwerpunkt auf Risikomanagement.

Mehr klare Empfehlungen

Im Laufe der Jahre haben wir viel Wissen darüber gesammelt, wie Kunden Snyk erfolgreich implementieren können – vom Onboarding bis zum täglichen Einsatz. Zu diesen Inhalten mit klaren Empfehlungen gehören ausführliche Anwendungsfälle, Schritt-für-Schritt-Anleitungen, Empfehlungen und weitere konkrete Leitlinien. Wir tragen dieses Wissen zusammen und veröffentlichen die Inhalte.

Diese Inhalte helfen allen Nutzern, jede Phase ihrer Snyk-Erfahrung zu planen. Außerdem wissen wir, dass unser wachsender Enterprise-Markt mehr Inhalte dieser Art benötigt: skalierbare und leicht zugängliche Schulungsmaterialien, mit denen Unternehmen ein effizientes Snyk-Onboarding für ihre Teams durchführen können.

Mit der Erstellung dieser Inhalte haben wir bei den Snyk-Implementierungsleitfäden im Abschnitt Implement Snyk begonnen.

Unsere nächsten Schritte

Unsere Reise mit der Dokumentation ist noch lange nicht zu Ende. 

Für 2024 planen und starten wir zahlreiche spannende Dokumentationsprojekte, darunter:

• Wir ergänzen die Dokumentation durchgehend um einheitliche Storytelling-Elemente, die unsere Kunden als Vorlagen nutzen können.

• Wir integrieren hilfreiche KI in die Nutzererfahrung, damit Sie schnell Antworten auf Ihre Fragen erhalten.

• Wir bringen Inhalte näher an die Nutzererfahrung, damit Sie schneller und gezielter auf Hilfe zugreifen können.

• Wir ergänzen die Dokumentation um ein einheitliches, ausführliches Änderungsprotokoll zu allen funktionalen Änderungen bei Snyk.

• Wir erweitern den Katalog mit Fehlermeldungen und veröffentlichen ihn vollständig.

Schauen Sie also regelmäßig in die Dokumentation, um mehr zu erfahren!