VuePress: Dokumentation leicht gemacht

Wenn es um ein Projekt geht, das eine Benutzerinteraktion erfordert (z. B. Endbenutzer, Betreuer usw.), gibt es einen entscheidenden Faktor, der über Erfolg und Misserfolg entscheidet: gute Dokumentation. Dies gilt unabhängig davon, wie klein oder groß Ihr Projekt ist. Schließlich ist die Dokumentation die erste Verteidigungslinie für Benutzer, die versuchen, ein Problem zu lösen, abgesehen von der Bereitstellung von Einzelunterstützung für Ihr Projekt. Und ob es Ihnen gefällt oder nicht, Sie werden nie von Benutzern hören, die aufgeben, weil sie ihr Problem aufgrund unzureichender Dokumentation nicht lösen konnten.

Die Herausforderungen beim Erstellen einer guten Dokumentation

Wenn es um das Schreiben einer guten Dokumentation geht, gibt es vier wiederkehrende Probleme, auf die Teams häufig stoßen:

1. Die Dokumentation ist oft veraltet.
   Während keine Dokumentation für ein Projekt eine frustrierende Erfahrung sein kann, ist es wohl noch schlimmer, eine veraltete Dokumentation zu haben. Schließlich besteht der Zweck der Dokumentation darin, den Benutzern eine offizielle Wissenssammlung zur Verfügung zu stellen, auf die sie sich verlassen können. Wenn es veraltet ist, verschwenden Benutzer ihre Zeit und verlieren letztendlich das Vertrauen in Ihr Produkt.
   
   Der Hauptgrund für das Veralten der Dokumentation ist, dass die Pflege der Dokumentation von Codeänderungen getrennt ist . Ohne viel Zeit und Energie zu investieren, kann dies schwierig zu lösen sein, weil:
   
   1. Die Dokumentation lebt normalerweise in einem Drittanbieterdienst wie Confluence oder einem Wiki.
   2. Entwickler sind in der Regel mehr daran interessiert, Code zu schreiben als an Dokumentation.
2. Benutzer können nicht einfach Feedback geben.
   Ganz gleich, wie gut Sie Ihre Dokumentation finden, sie ist letztendlich bedeutungslos, ohne sie mit echten Benutzern zu testen, die Feedback geben können. Wie bereits erwähnt, besteht eine häufige Tendenz bei der Bewertung der Effektivität von Dingen wie der Dokumentation darin, Benutzer nicht zu berücksichtigen, die ihre Probleme nicht lösen konnten und aufgegeben haben. Da kein Team jemals in der Lage wäre, jedes Szenario zu berücksichtigen, wie Benutzer Ihr Produkt verwenden könnten, müssen Benutzer eine einfache und zuverlässige Möglichkeit haben, Feedback zu geben.
3. Dokumentation wird oft von Power-Usern für Power-User geschrieben.
   Der Nachteil bei der Verwendung von Standardwerkzeugen wie Wikis oder README-Dateien besteht darin, dass sie sich oft nur an eine bestimmte Gruppe von Benutzern richten, die oft bereits über ein bereits vorhandenes Wissen über die Bibliothek und/oder den Technologie-Stack verfügen. Infolgedessen ist es für sie ziemlich einfach, sich im Raum zurechtzufinden und zu finden, was sie brauchen. Neuen Benutzern fehlt jedoch dieses Vorwissen und sie benötigen daher oft eine viel intensivere Erfahrung, um sie zu engagieren.
   
   Beispiele hierfür sind:
   
   • Eine gut gestaltete Website,
   • Suchfunktion,
   • Geführte Seitennavigation,
   • Leicht identifizierbare Metainformationen (z. B. Datum der letzten Aktualisierung),
   • Immersive Inhalte, die über eine schwer verständliche Textwand hinausgehen.
4. Schlechte Infrastruktur, die die Pflege der Dokumentation erschwert.
   Als ob es nicht schwierig genug wäre, eine gute Dokumentation zu schreiben, die Benutzer verstehen können, ist die Leichtigkeit, mit der ein Entwickler Dokumentation schreiben und/oder pflegen kann, entscheidend für ihre langfristige Rentabilität. Je zusätzliches Hindernis also, mit dem sich Entwickler beim Schreiben und/oder Pflegen von Dokumentation auseinandersetzen müssen, desto wahrscheinlicher ist es, dass sie letztendlich scheitern wird. Aus diesem Grund ist es wichtig, dass die Erstellung und Pflege von Dokumentationen so nahtlos und ansprechend wie möglich sind.

Wenn es nur ein Tool gäbe, das all diese Dinge für uns erledigen könnte …

Geben Sie VuePress ein

Wenn man zum ersten Mal von VuePress hört, könnte man versucht sein zu vermuten, dass es sich um eine Verschmelzung von Vue.js und WordPress handelt. Stattdessen sollten Sie sich VuePress wie folgt vorstellen:

Vue.js + Druckmaschine

Denn letzten Endes ist VuePress ein statischer Seitengenerator!

Einige von Ihnen denken vielleicht: „Warte. Ein weiterer statischer Site-Generator? Was ist die große Sache?“

Während es eine Reihe von Tools gibt, die statische Site-Generatoren sind, hebt sich VuePress aus einem einzigen Grund von der Masse ab: Seine Hauptrichtlinie besteht darin, es Entwicklern zu erleichtern, großartige Dokumentationen für ihre Projekte zu erstellen und zu pflegen.

Warum ist VuePress so leistungsfähig für die Erstellung von Dokumentationen?

Die Antwort ist einfach. Es wurde mit einem Ziel entwickelt: Entwicklern dabei zu helfen, großartige Dokumentationsseiten zu erstellen und gleichzeitig ein unterhaltsames Authoring-Erlebnis zu erhalten. Dies bedeutet, dass es einen Rahmen für Entwickler bietet, um:

• Erstellen Sie schöne Dokumentationsseiten,
• Kommen Sie mit vorgefertigten Funktionen, die für alle Dokumentationsseiten unerlässlich sind,
• Optimieren Sie das Authoring-Erlebnis, um es so einfach wie das Aktualisieren einer Markdown-Datei zu machen.

VuePress kann mit Ihrer bestehenden Codebasis koexistieren

Dies ist einer der Hauptgründe, warum ich es dringend empfehle. Wenn es um die Pflege der Dokumentation geht, besteht eine Möglichkeit, sicherzustellen, dass sie nicht mehr aktuell ist, darin, Entwicklern das Aktualisieren von Dokumenten beim Schreiben von Code zu erschweren. Wenn Sie das Autorenerlebnis erschweren, indem Sie Entwickler zwingen, Dinge an zwei verschiedenen Stellen zu aktualisieren, führt dies zu viel Reibung und führt häufig dazu, dass die Dokumentation auf der Strecke bleibt. Dies ist häufig der Fall, wenn Entwickler zusätzlich zur Codebasis selbst ein Drittanbieter-Tool wie ein Wiki pflegen müssen.

Da es sich um einen statischen Site-Generator handelt, bedeutet dies, dass er genau in demselben Repo wie Ihr Code leben kann.

Wie Sie in dieser Beispiel-Web-App-Struktur sehen können, würde Ihr Code wie gewohnt im src -Verzeichnis gespeichert, aber Sie hätten einfach ein docs -Verzeichnis, das Ihre gesamte Dokumentation enthält. Das heißt, Sie profitieren von:

• Die gesamte Dokumentation ist jetzt versioniert;
• Pull-Requests können jetzt sowohl Dokumentations- als auch Codeänderungen enthalten;
• Erstellen separater Skripte zum gleichzeitigen Ausführen lokaler Instanzen Ihres Codes und Ihrer Dokumente;
• Verwenden Sie Build-Pipelines, um zu bestimmen, ob neue Bereitstellungen von Dokumentationsseiten mit Codebereitstellungen synchronisiert werden oder nicht.

Das Standarddesign wird mit der Standardkonfiguration geliefert

Das Schreiben von Dokumentation ist ohnehin schon schwierig genug, daher entlastet VuePress viele der Entscheidungen, die man normalerweise treffen muss, und verfügt über eine Reihe integrierter Standardeinstellungen, um Ihre Autorenerfahrung zu vereinfachen:

• Das Schreiben von Inhalten erfolgt hauptsächlich mit Markdown.
  Das bedeutet, dass Sie Ihr vorhandenes Wissen über die Markdown-Syntax nutzen können, um Ihren Text zu gestalten und zu formatieren.

• Hervorhebung der Codesyntax.
  Wenn Sie eine Website ganz alleine erstellen würden, müssten Sie mit Bibliotheken zur Hervorhebung der Syntax in Farbe ringen. Aber Sie haben Glück, denn das Hinzufügen von Codeblöcken in VuePress ist so einfach, da alles ohne Konfiguration einsatzbereit ist.

• Titelseite zum Definieren von Metadaten auf Seitenebene.
  Auch wenn Sie in einer Markdown-Datei schreiben, können Sie Front Matter (wie YAML, JSON oder TOML) verwenden, um Metadaten für Ihre Seite zu definieren, um die Verwaltung Ihrer Inhalte noch einfacher zu machen!

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Benutzerdefinierte Markdown-Container.
  Falls Sie es nicht wussten, Markdown verfügt über Erweiterungen, um noch nützlichere Verknüpfungen hinzuzufügen, um schöne UI-Komponenten wie benutzerdefinierte Container zu erstellen. Und da sie in der Dokumentation so nützlich sind, hat VuePress sie bereits so konfiguriert, dass Sie sie sofort verwenden können:

Integrierte Suchfunktion

Seien wir ehrlich. Egal, wie viel Zeit wir damit verbringen, großartige Dokumentation zu schreiben, sie wird letztendlich nutzlos sein, wenn die Benutzer sie nicht finden können. Dafür gibt es grundsätzlich zwei Vorgehensweisen:

1. Warten Sie, bis die Suchmaschinenroboter Ihre Website langsam crawlen, in der Hoffnung, dass Ihre Benutzer eines Tages die richtige Seite auf Ihrer Website finden können. Keine tolle Lösung.
2. Erstellen Sie Ihre eigene Suchfunktion, aber dies kann für statische Websites schwierig zu implementieren sein, da kein serverseitiger Code ausgeführt wird, um Suchindizes zu erstellen und die Suchen durchzuführen. Ganz zu schweigen davon, dass dies dem Produkt selbst Entwicklungszeit nimmt. Das ist also auch nicht toll.

Zum Glück für uns ist VuePress hier, um den Tag wieder einmal zu retten!

VuePress verfügt über eine integrierte Suchfunktion, die eine eigene „Suchmaschine“ generiert – Sie haben richtig gelesen. Ohne zusätzliche Datenbankeinrichtung oder -konfiguration ist VuePress so eingerichtet, dass es Ihre gesamten Dokumente kratzt, um eine einfache Suchmaschine zu generieren, die alle Ihre h1s und h2s für Ihren Benutzer anzeigt.

Manche denken jetzt vielleicht,

„Was ist, wenn ich etwas möchte, das eine Indizierung auf niedrigerer Ebene für die Suche bereitstellt?“

Nun, VuePress hat Sie auch dort abgedeckt, weil es so konzipiert ist, dass es sich leicht in Algolia DocSearch integrieren lässt, das Ihnen diese Funktionalität kostenlos zur Verfügung stellen kann, wenn Sie ihre Anforderungen erfüllen:

Die Sidebar-Navigation ist so einfach wie das Ein- oder Ausschalten der Funktion

Jeder, der jemals für die Verwaltung von Inhalten verantwortlich war, weiß, wie kompliziert es sein kann, eine Seitenleiste mit verschachtelten Elementen zu erstellen und dann zu verfolgen, an welcher Position sich der Leser befindet, während er nach unten scrollt. Warum also die Zeit damit verbringen, wenn Sie bessere Dokumente schreiben könnten? Bei VuePress ist die Seitenleiste so einfach wie das Umschalten auf die Titelseite einer Seite:

Automatische Generierung wichtiger Metadaten, die häufig übersehen werden

Eines der frustrierendsten Dinge, denen ein Benutzer begegnen kann, ist veraltete Dokumentation. Wenn ein Benutzer die Schritte befolgt und Schwierigkeiten hat zu verstehen, warum etwas nicht funktioniert, kann es sowohl für den Benutzer als auch für die Betreuer des Projekts unglaublich nützlich sein, das Datum der letzten Aktualisierung leicht herauszufinden.

Mit einer einfachen Konfiguration kann VuePress sicherstellen, dass automatisch das Datum der letzten Aktualisierung auf der Seite ausgegeben wird, sodass Ihre Benutzer immer wissen, wann sie zuletzt aktualisiert wurde.

Darüber hinaus macht es VuePress mit ein wenig Konfiguration für Benutzer unglaublich einfach, zu Ihren Dokumenten beizutragen, indem automatisch ein Link am Ende jeder einzelnen Seite generiert wird, der es Benutzern ermöglicht, ganz einfach eine Pull-Anfrage zu Ihren Dokumenten zu erstellen.

Einfacher geht es für Ihre Nutzer nicht.

Bereitstellung auf jeder statischen Hosting-Site

Da VuePress im Kern ein statischer Website-Generator ist, bedeutet dies, dass Sie es auf jeder gängigen Hosting-Plattform einsetzen können, wie z. B.:

• Netlify
• GitHub-Seiten
• GitLab-Seiten
• Heroku
• Jetzt

Alles, was Sie tun müssen, um die Site zu erstellen, ist, vuepress build {{ docsDir }} mit Ihrem Verzeichnis auszuführen, und Sie haben alles, was Sie brauchen, um es live im Web bereitzustellen!

Hinweis : Ausführlichere Anleitungen dazu finden Sie in den offiziellen Bereitstellungsanleitungen für VuePress.

Nutzung von Vue in Ihrer Markdown-Datei

Ich weiß, ich weiß. Wir können Vue.js in unserem Markdown verwenden?! Ja, Sie haben richtig gelesen! Obwohl dies technisch optional ist, ist dies wahrscheinlich einer der aufregendsten Aspekte von VuePress, da Sie damit Ihre Markdown-Inhalte verbessern können, wie Sie es noch nie zuvor konnten.

Definieren Sie sich wiederholende Daten an einem Ort und lassen Sie sie überall mit Interpolation aktualisieren

Im folgenden Beispiel sehen Sie ein kurzes Beispiel dafür, wie Sie lokale Variablen (wie die in der Frontmatter definierten) sowie global definierte (wie den Seitentitel) nutzen können:

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Verwenden Sie Vue-Komponenten innerhalb von Markdown

Ich gebe Ihnen einen Moment, um sich zu sammeln, nachdem Sie dies gelesen haben, aber ja, Live-Vue-Komponenten mit einer vollständigen Vue-Instanz können Ihnen gehören, wenn Sie möchten! Die Konfiguration erfordert etwas mehr Arbeit, aber das ist zu erwarten, da Sie benutzerdefinierte Inhalte erstellen, die in Ihrer Dokumentation ausgeführt werden.

Hier ist ein kurzes Beispiel dafür, wie eine Counter-Komponente in einer Markdown-Datei aussehen würde:

Dies ist vielleicht der leistungsfähigste Teil der Anpassung, der für die Dokumentation verfügbar ist, da Sie jetzt die Freiheit haben, benutzerdefinierte Inhalte zu erstellen, die weit über die Fähigkeiten von Standard-Markdown hinausgehen. Ob es also darum geht, eine Demo oder einen interaktiven Code bereitzustellen, die Ideen sind endlos!

Nächste Schritte

Wenn Sie eine schöne Dokumentationsseite für Ihre Benutzer einrichten möchten, um zu lernen, wie Sie Ihr Produkt verwenden, geht es nicht viel einfacher als mit VuePress. Und auch wenn man leicht annehmen könnte, dass VuePress nur von Projekten verwendet werden sollte, die Vue.js verwenden, könnte dies nicht weiter von der Wahrheit entfernt sein. Hier sind nur einige Beispiele für die verschiedenen Arten von Projekten, die VuePress für ihre Dokumentationsseiten nutzen:

• Craft-CMS
• UmiJS (das für React entwickelt wurde)
• öffnenHAB
• Pfau

Unabhängig davon, ob Sie VuePress verwenden oder nicht, hoffe ich, dass dies letztendlich dazu beigetragen hat, Sie dazu zu inspirieren, eine bessere Dokumentation für Ihre Benutzer zu erstellen.

Weitere Ressourcen

Es gibt viele coole Dinge, die ich hier in diesem Artikel nicht behandelt habe (z. B. Thematisierung, Bloggen usw.), aber wenn Sie mehr erfahren möchten, sehen Sie sich diese Ressourcen an:

• Offizielle VuePress-Dokumentation
• Eine kuratierte Liste von VuePress-bezogenen Ressourcen
• VuePress-Galerie
• Boilerplate des VuePress-Blogs