Eine Dokumentationswebsite erstellen

Dokumentation gibt es in vielen Formen. Sie haben möglicherweise bereits einige Ressourcen oder müssen von Grund auf neu beginnen. Lassen Sie uns durchgehen, wie Sie Inhalte mit Archbee hinzufügen können.

Sobald Sie ein neues Dokument erstellt haben, können Sie beginnen, Inhalte hinzuzufügen, entweder mit Markdown-Kurzbefehlen oder einem der 30+ benutzerdefinierten Blöcke.

Die benutzerdefinierten Blöcke helfen Ihnen, den Inhalt nach Bedarf zu formatieren. Um sie zu öffnen, tippen Sie einen Schrägstrich / im Editor und gehen Sie die Optionen durch.

Die Blöcke sind gruppiert unter Grundlegend, Medien, Dev, Einbetten, und Inhaltswiederverwendung.

Wenn Sie beispielsweise dynamisch auf andere Dokumente verlinken möchten, tippen Sie @ und den Dokumenttitel. Dies stellt eine Verbindung zur Dokument-ID her. Wenn Sie den Titel oder die Position des Dokuments ändern, wird der Link immer darauf verweisen.

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

Die dritte Option besteht darin, Klammern und den Namen des Blocks zu verwenden – z. B. (api) – dies fügt den API-Endpoint-Block hinzu.

Die altbewährten Copy-Paste-Brüder. Aber warum darauf eingehen? Da der Editor von Archbee Markdown unterstützt, kann es sein, dass Sie beim Einfügen in diesem Format die folgende Meldung erhalten:

Wenn Sie auf die Schaltfläche Abbrechen klicken, wird der Inhalt nicht gerendert, und wenn Sie im Dialogfeld auf OK klicken, konvertieren wir das Markdown in Archbee-Blöcke.

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

Copy-Pasting funktioniert einwandfrei, aber wenn Sie Markdown- oder Word-Dateien haben, warum diese nicht in einen Space importieren?

Bevor Sie Inhalte importieren, stellen Sie sicher, dass Sie auf den Space klicken, in den Sie die Dateien importieren möchten. Sie haben gerade auf den Dateityp geklickt, den Sie besitzen, und dadurch Minuten an Copy-Paste-Arbeit gespart.

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

Nehmen wir an, Sie verwenden den OpenAPI-Standard (früher Swagger). Dies ermöglicht einen einfachen Import und Sync der Dateien.

Sobald der Inhalt in Archbee importiert wurde, wird er in einem 3-Spalten-Layout dargestellt, das eine leicht zu verwaltende Dokumentation ermöglicht.

Es kommt vor, dass die Dokumentation in einem GitHub-Repository geschrieben wird. 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 weitere Spaces mit zusätzlichen Informationen wie API-Referenzen hinzufügen können.

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

Unter dem Tab Allgemein stehen mehrere Optionen zur Verfügung – Sie können Durch Suchmaschinen indexierbar (falls öffentlich) in den selben Space Einstellungen deaktivieren. Oft möchten Sie dies aktiviert lassen, damit Nutzer Ihre Seite in den Suchergebnissen finden. Sie können die Option Public Access Control öffnen und eine der fünf Optionen für mehr Kontrolle auswählen.

Bevor Sie Dokumentation schreiben, überlegen Sie sich die Hauptthemen, die Sie abdecken werden. Dieses Mal können Stift und Papier helfen, 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 Hauptaspekte einführt, die ein Nutzer auf der Dokumentationsseite finden wird. Es muss nicht kompliziert sein; so haben wir es in unserem Benutzer- & Dev-Handbuch gemacht:

Im Tab Darstellung finden Sie die Branding-Optionen wie Akzentfarbe, Logo, und Favicon, zusammen mit weiteren Optionen für die Vorlage.

Je nach Art der Produkte oder Dienstleistungen möchten Sie möglicherweise unterschiedliche Space-URL-Pfade haben.

Sie können einen Space als primäre Dokumentation haben und verschiedene 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, die Struktur beizubehalten und die Änderungen für die neue Version vorzunehmen.

Wenn Versionierung und Multiprodukt also etwas ist, 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 zu helfen, zur nächsten Seite zu gelangen.

Beim Erstellen einer Landingpage für Ihre Dokumentations-Website müssen nicht dieselben Praktiken wie für eine Präsentations-Website berücksichtigt werden.

Die erste Dokumentseite ist wichtig, um Ihr Produkt oder Ihre Dienstleistung den Nutzern vorzustellen. Daher ist es sinnvoll, sie kurz zu halten und Erwartungen zu setzen.

Sie können die Funktion Benutzerdefinierte Landingpage verwenden und Ihr eigenes HTML hinzufügen, um mehr Kontrolle über die erste Seite zu haben. Es gibt viele Optionen zur Inspiration, und wenn Sie das Erscheinungsbild der ersten Seite ändern möchten, ist dies die richtige Wahl.

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

Verwenden Sie Benutzerdefiniertes CSS wenn Sie Ihrer Dokumentationsseite Ihren eigenen Geschmack hinzufügen möchten. Wenn Sie mit CSS-Klassen vertraut sind, finden Sie einige Ausgangspunkte und können diese gezielt ansprechen.