Eine Dokumentationswebsite erstellen

Dokumentation gibt es in vielen Formen und Varianten. Möglicherweise verfügen Sie bereits über einige Ressourcen oder müssen bei null anfangen. Sehen wir uns an, wie Sie Inhalte mit Archbee hinzufügen.

Sobald Sie ein neues Dokument erstellen, können Sie Inhalte entweder mit Markdown-Shortcuts oder einem der 30+ benutzerdefinierten Blöcke hinzufügen.

Die benutzerdefinierten Blöcke helfen Ihnen dabei, Inhalte nach Bedarf zu formatieren. Um sie zu öffnen, geben Sie einen Schrägstrich / im Editor ein und sehen Sie sich die Optionen an.

Die Blöcke sind unter Grundlegend, Medien, Entwickler, Einbetten, und Wiederverwendung von Inhalten gruppiert.

Wenn Sie beispielsweise dynamisch auf andere Dokumente verlinken möchten, geben Sie @ und den Dokumenttitel ein. Dadurch wird eine Verbindung zur Dokument-ID hergestellt. Wenn Sie den Titel oder die Position des Dokuments ändern, verweist der Link weiterhin darauf.

Ein weiteres Beispiel ist das Aufrufen des Blocknamens. Geben Sie / ein und tippen Sie den Namen des Blocks, z. B. /verticalsplit ein, wodurch der gewünschte Block herausgefiltert wird.

Die dritte Option besteht darin, Klammern und den Namen des Blocks zu verwenden – z. B. (api) – wodurch der API-Endpunkt-Block hinzugefügt wird.

Die altbewährten Brüder Kopieren und Einfügen. Aber warum sollte man das behandeln? Da der Editor von Archbee Markdown unterstützt, erhalten Sie möglicherweise die folgende Meldung, wenn Sie Inhalte in diesem Format einfügen möchten:

Wenn Sie auf die Schaltfläche „Cancel“ klicken, wird der Inhalt nicht gerendert. Wenn Sie im Dialogfeld auf „OK“ klicken, konvertieren wir das Markdown in die Blöcke von Archbee.

Sie haben also ein Codebeispiel, das in Archbee als Code-Editor-Block gerendert wird.

Kopieren und Einfügen funktioniert einwandfrei, aber wenn Sie Markdown- oder Word-Dateien haben, warum importieren Sie sie nicht in einen Space?

Bevor Sie Inhalte importieren, stellen Sie sicher, dass Sie auf den Space klicken, in den Sie die Dateien importieren möchten. Sie müssen nur auf den Dateityp klicken, den Sie haben, und sparen sich Minuten des Kopierens und Einfügens aus anderen Quellen.

Wenn es um die Dokumentation von APIs geht, haben Sie mehrere Optionen.

Angenommen, Sie verwenden den OpenAPI-Standard (früher Swagger). Dies ermöglicht ein einfaches Importieren und Synchronisieren der Dateien.

Sobald die Inhalte in Archbee importiert wurden, werden sie in einem 3-Spalten-Layout gerendert, das eine einfach zu verwaltende Dokumentation ermöglicht.

Es kommt vor, dass die Dokumentation in einem GitHub-Repository geschrieben wird, und Sie können weiterhin in GitHub schreiben und das Repository mit einem Archbee Space synchronisieren. Der Vorteil besteht darin, dass Sie diesen Space auf Ihrer benutzerdefinierten Domain veröffentlichen und andere Spaces mit zusätzlichen Informationen wie API-Referenzen hinzufügen können.

Bevor Sie mit den Inhalten beginnen, unternehmen Sie einen kleinen Schritt, der später einen Unterschied machen wird. Richten Sie Ihre Subdomain ein, um Zugriff auf die Vorschau- und Produktionsumgebungen zu erhalten. Gehen Sie zur Dokumentationsseite und folgen Sie den Schritten, um Ihre benutzerdefinierte Domain hinzuzufügen.

Mehrere Optionen sind unter der Registerkarte Allgemein verfügbar – Sie können die Option Von Suchmaschinen indexierbar (wenn öffentlich) in denselben Space Settings deaktivieren. In vielen Fällen möchten Sie diese Option aktiviert lassen, damit Benutzer Ihre Website auf der Ergebnisseite von Suchmaschinen finden können. Sie können zur Option „Public access control“ wechseln und eine der fünf Optionen für mehr Kontrolle auswählen.

Bevor Sie Dokumentation schreiben, sollten Sie die Hauptthemen berücksichtigen, die Sie behandeln werden. Diesmal könnten Stift und Papier hilfreich sein, um die Struktur zu skizzieren.

Erstellen Sie als Nächstes ein Dokument, konvertieren Sie es in eine Kategorie und geben Sie ihm einen Namen.

Sobald Sie diese haben, können Sie Dokumente unter jeder Kategorie hinzufügen.

Beginnen Sie mit einem Dokument, das die wichtigsten Dinge vorstellt, die ein Benutzer auf der Dokumentationsseite finden wird. Es muss nicht kompliziert sein; so haben wir es in unserem Benutzer- & Entwicklerhandbuch: gemacht

Wenn Sie beginnen, Inhalte hinzuzufügen, ist es wichtig, einen Workflow zu haben. Hier ist ein möglicher Workflow, den Sie jedoch möglicherweise anpassen möchten:

Die Arbeit mit Vorlagen erleichtert es Mitwirkenden, mit dem Schreiben von Inhalten zu beginnen. Sie können eine Reihe von Vorlagen speichern, um die Inhaltserstellung schneller zu starten. Wenn Sie Inspiration benötigen, sehen Sie beim Erstellen eines neuen Dokuments unten auf der Seite eine Schaltfläche mit dem Namen: Start with a template. Um eigene Vorlagen zu erstellen, gehen Sie zur Navigation auf der linken Seite, zu Templates, und beginnen Sie damit, Dokumente mit der Struktur zu erstellen, die Ihre Dokumente benötigen.

Sie können außerdem die benutzerdefinierten Blöcke vorstellen, die ein Autor verwenden wird, oder Beispiele aus anderen Quellen hinzufügen.

Diese Optionen befinden sich auf Dokumentebene. Sie müssen also auf die drei Punkte ⋮ oben rechts klicken und SEO-Meta-Steuerung auswählen.

Fügen Sie einen relevanten Titel hinzu, ändern Sie die URL, schreiben Sie eine Meta-Beschreibung oder laden Sie ein Bild hoch für Vorschauen.

Im Tab Erscheinungsbild finden Sie Branding-Optionen wie Akzentfarbe, Logo und Favicon, zusammen mit weiteren Optionen für das Template.

Abhängig von der Art der Produkte oder Services möchten Sie möglicherweise unterschiedliche Space-URL-Pfade verwenden.

Sie können einen Space als primäre Dokumentation verwenden und unterschiedliche Spaces für andere Produkte oder sogar deren Versionen erstellen.

Es gibt eine Abkürzung! Sie können einen Klon eines beliebigen Space erstellen, wenn die Änderungen inkrementell sind. Dies hilft Ihnen dabei, die Struktur beizubehalten und die Bearbeitungen für die neue Version vorzunehmen.

Wenn Versionierung und mehrere Produkte also etwas sind, das Sie benötigen, verwenden Sie unterschiedliche Spaces und ergänzen Sie diese mit dem entsprechenden Pfad oder einer benutzerdefinierten Domain.

Gehen Sie zu Space-Links und beginnen Sie mit dem Aufbau Ihrer Navigation.

Das Hauptziel der Homepage besteht darin, dem Besucher dabei zu helfen, zur nächsten Seite zu gelangen.

Beim Erstellen einer Landingpage für Ihre Dokumentationswebsite müssen Sie nicht dieselben Praktiken wie für eine Präsentationswebsite anwenden.

Die erste Dokumentationsseite ist wichtig, um Benutzern Ihr Produkt oder Ihren Service vorzustellen. Daher hilft es sehr, sie kurz zu halten und Erwartungen festzulegen.

Sie können die Funktion Benutzerdefinierte Landingpage verwenden und Ihr eigenes HTML hinzufügen, um mehr Kontrolle über die erste Seite zu erhalten. Es gibt viele Möglichkeiten, sich inspirieren zu lassen, und wenn Sie das Erscheinungsbild der ersten Seite ändern möchten, ist dies Ihre Option.

Hier sehen Sie, wie einer unserer Kunden die Startseite für seine Hilfeseite erstellt hat.

Verwenden Sie Benutzerdefiniertes CSS wenn Sie Ihre eigene Note zur Dokumentationswebsite hinzufügen möchten. Wenn Sie mit CSS-Klassen vertraut sind, finden Sie einige grundlegende ab- und können diese gezielt ansprechen.