Beim Verfassen von Produkt- oder technischer Dokumentation ist es entscheidend, Ihre Inhalte klar zu strukturieren und visuell intuitiv darzustellen. Dies hilft Lesern, die Kernpunkte schnell zu erfassen und reduziert den Aufwand, der zum Verständnis der Inhalte erforderlich ist.
Apidog, als API-Management-Tool, ermöglicht nicht nur eine effiziente Verwaltung der API-Dokumentation, sondern erlaubt Teams auch, professionelle Produktdokumente mithilfe flexibler Markdown-Syntax zu erstellen. Die Apidog-Hilfedokumentation für Benutzer wird mit den Markdown-Funktionen von Apidog erstellt.
Nachfolgend finden Sie 10 praktische Tipps zum Schreiben von Produktdokumentation mit Markdown in Apidog.
1. Den Titel der Seitenleiste anpassen
Wenn Sie ein neues Markdown-Dokument in Apidog erstellen, wird der Titel des Markdown-Dokuments standardmäßig als Titel der Seitenleiste verwendet, wie unten gezeigt:
Wenn Sie möchten, dass sich die Titel der Seitenleiste und des Dokuments unterscheiden, können Sie diese separat anpassen.
Sie können beispielsweise "Übersicht" als Titel der Seitenleiste verwenden und dem Dokument einen spezifischeren Titel wie "APIs in Apidog entwerfen" geben.
So richten Sie es ein: Klicken Sie im Markdown-Dokument auf "Titel der Seitenleiste" und ändern Sie den Titel.
Die Verwendung unterschiedlicher Titel für die Seitenleiste und das Dokument hat zwei Vorteile:
- Der Titel der Seitenleiste bleibt kurz und übersichtlich, wodurch die Ordnerstruktur sauber bleibt.
- Der Dokumenttitel kann für mehr Klarheit detaillierter und beschreibender sein.
Wenn Sie einen Dokumentlink auf Plattformen wie Slack teilen, erscheint der Dokumenttitel in der Vorschau, wodurch der Link klarer und leichter verständlich aussieht. Hier ist ein Beispiel, wie es in Slack aussieht:
2. Projektressourcen und Schemas zitieren
Apidog macht es einfach, Endpunkte, Dokumente und Schemas aus Ihrem Projekt direkt in Markdown-Dateien zu zitieren.
Zum Zitieren von Endpunkten und Markdown-Dokumenten:
- Öffnen Sie Ihr Markdown-Dokument und klicken Sie auf "Endpunkt/Markdown im Projekt einfügen".
- Wählen Sie die Ressource aus, die Sie einfügen möchten (Endpunkt oder Markdown-Dokument).
Der zitierte Inhalt wird automatisch mit der Zielressource im Projekt verknüpft, und ein Klick darauf in der Vorschauansicht springt zu dieser Detailseite.
Zum Zitieren von Schemas:
- Gehen Sie zu "Einfügen" → "Datenschema".
- Wählen Sie das gewünschte aus.
Alle Änderungen, die Ihr Team am Datenschema vornimmt, werden automatisch mit der zitierten Version synchronisiert, wodurch sichergestellt wird, dass Ihre Dokumentation immer aktuell bleibt. Dies verhindert Verwirrung und Fehler, die durch veraltete Informationen verursacht werden.
Beispielcode:
<DataSchema id="4700682" />
3. Link-Verhalten und Navigation steuern
Apidog Markdown unterstützt verschiedene Linktypen, deren Verhalten in der Online-Dokumentation variiert:
- Einige Links öffnen in einem neuen Browser-Tab
- Einige öffnen auf der aktuellen Seite
- Andere springen direkt zu einem bestimmten Abschnitt im Dokument mithilfe von Ankern
Die Wahl des richtigen Linktyps erleichtert die Navigation und hilft Benutzern, die benötigten Informationen schnell zu finden.
Nachfolgend finden Sie Details dazu, wie jeder Linktyp funktioniert und wie er konfiguriert wird.
3.1 Links, die auf der aktuellen Seite geöffnet werden
Links, die über "Endpunkt/Markdown im Projekt einfügen" hinzugefügt werden, generieren Adressen, die mitapidog://link/pages/... beginnen und beim Anklicken auf der aktuellen Browserseite geöffnet werden.
Zum Beispiel:
[Overview](apidog://link/pages/990068)
So richten Sie es ein: Klicken Sie auf die Schaltfläche "Endpunkt/Markdown im Projekt einfügen" und wählen Sie den gewünschten Endpunkt oder das Dokument aus.
Links wie apidog://link/pages/... können in Apidog Markdown als normale Links verwendet werden. Nach dem Veröffentlichen oder Teilen werden sie automatisch in tatsächliche Online-Adressen (z. B. https://xxx.apidog.io/xxx) umgewandelt und unterstützen Sprungfunktionen. Zum Beispiel in einer "Card"-Komponente:
<Card title="Click here" href="apidog://link/pages/990068">
This is a card, click to jump to the target page
</Card>
3.2 Links, die in einem neuen Tab geöffnet werden
Jeder Link, der nicht über "Endpunkt/Markdown im Projekt einfügen" hinzugefügt wird, öffnet sich standardmäßig in einem neuen Browser-Tab. Zum Beispiel:
[API-design first approach](https://docs.apidog.com/api-design-first-approach-533942m0)
3.3 Anker-Links, die in einem neuen Tab geöffnet werden
Um direkt zu einem bestimmten Abschnitt im Inhaltsverzeichnis (TOC) zu verlinken, fügen Sie am Ende Ihres Links einen Anker (z. B. #xxx) hinzu. Zum Beispiel:
[these methods are the same as those used for inviting users to the team](https://docs.apidog.com/managing-team-members-613028m0#invitation-methods)
3.4 Anker-Links, die auf der aktuellen Seite geöffnet werden
Sie können auch Anker in internen Projektlinks verwenden, um zu einem bestimmten Abschnitt innerhalb desselben Dokuments zu springen. Zum Beispiel:
[these methods are the same as those used for inviting users to the team](apidog://link/pages/613028#invitation-methods)
Anker-Links wie apidog://link/pages/613028#invitation-methods funktionieren erst, nachdem die Seite geteilt oder veröffentlicht wurde. Wenn Sie diese Links im Apidog-Client vor der Veröffentlichung anklicken, geschieht nichts, da der Link noch nicht in einen zugänglichen Webpfad umgewandelt wurde.
Die oben genannten Links können entweder im Markdown- oder HTML-Format vorliegen, zum Beispiel:
Link, der auf der aktuellen Seite geöffnet wird:
<a href="apidog://link/pages/533969">Design APIs in Apidog</a>
Link, der in einem neuen Tab geöffnet wird:
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0">Design APIs in Apidog</a>
Anker-Link (öffnet in einem neuen Tab):
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0#design-apis">Design APIs in Apidog</a>
Anker-Link (öffnet auf der aktuellen Seite):
<a href="apidog://link/pages/533969#design-apis">Design APIs in Apidog</a>`4. Nebeneinanderliegende Layouts mit Containern und Spalten erstellen
Wenn Sie Unterschiede zwischen Versionen, Funktionsvergleiche oder parallele Informationen darstellen müssen, verwenden Sie die "Container"-Komponente, verschachtelt mit der "Column"-Komponente, um ein visuell ansprechendes Nebeneinander-Layout zu erstellen.
Dieses Layout erleichtert Lesern den schnellen Vergleich von Inhalten, verbessert die Klarheit und Kommunikation.
Zum Beispiel:
So richten Sie es ein: Wählen Sie im Markdown-Dokument "Container" und dann "Mehrere Spalten → 2 Spalten". Sie können jede Spalte mit Inhalt füllen, z. B. Beschreibungen für "Alte Version" und "Neue Version".
Beispiel für Markdown-Syntax:
<Container>
<Columns>
<Column>
**Alte Version**
</Column>
<Column>
**Neue Version**
</Column>
</Columns>
---
<Columns>
<Column>
Hier ist der Inhalt der alten Version
<DataSchema id="4700681" />
</Column>
<Column>
Hier ist der Inhalt der neuen Version
<DataSchema id="8144258" />
</Column>
</Columns>
</Container>💡 Im obigen Markdown bezieht sich <DataSchema id="xxxxxx" /> auf ein Schema im Projekt.
5. Schritt-Komponente für visuelle Anleitungen verwenden
Für praktische Tutorials oder Feature-Anleitungen verwenden Sie die "Schritt"-Komponente in Apidog Markdown, um komplexe Prozesse in einfache, leicht verständliche Schritte zu unterteilen.
Dieses geführte Design hilft, Benutzerverwirrung zu reduzieren und die Erfolgsraten zu verbessern, insbesondere für neue Benutzer oder beim Erklären komplexer Funktionen.
Die "Schritt"-Komponente nummeriert jeden Schritt automatisch und fügt visuelle Hinweise hinzu, um den Prozess klar und ansprechend zu gestalten.
Zum Beispiel:
So richten Sie es ein: Wählen Sie im Markdown-Dokument die "Schritt"-Komponente aus und geben Sie detaillierte Inhalte für jeden Schritt ein.
Beispiel für Markdown-Syntax:
<Steps>
<Step title="Erster Schritt">
Dies sind Anweisungen oder Inhalte, die nur den ersten Schritt betreffen.
</Step>
<Step title="Zweiter Schritt">
Dies sind Anweisungen oder Inhalte, die nur den zweiten Schritt betreffen.
</Step>
<Step title="Dritter Schritt">
Dies sind Anweisungen oder Inhalte, die nur den dritten Schritt betreffen.
</Step>
</Steps>
6. Bildanzeige und Layout verbessern
In Apidog Markdown ist das Einfügen von Bildern einfach. Sie können Bilder von Ihrem Computer hochladen oder direkt in den Editor einfügen.
Bildlinks können von Drittanbieter-CDNs stammen, wie zum Beispiel:
Sowohl Markdown- als auch HTML-Syntax werden zum Einfügen von Bildern unterstützt, zum Beispiel:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog"/>Mit HTML können Sie Inline-CSS-Stile hinzufügen, wie z. B. die Angabe von Breite, Höhe und Zentrierung:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;display: block; margin: 0 auto"/>
// oder
<div style="text-align: center;">
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;" />
</div>Im Dunkelmodus wird, wenn das Bild Transparenz aufweist, der Hintergrund standardmäßig weiß. Um den weißen Hintergrund zu entfernen, verwenden Sie Inline-CSS:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="background-color: transparent;"/>Um die Bildpräsentation professioneller und schöner zu gestalten, können Sie dem Bild einen Hintergrund hinzufügen:
<Background>
</Background>Oder fügen Sie dem Bild einen Rahmen und eine Bildunterschrift hinzu:
<Frame caption="Darstellungseinstellungen">
</Frame>7. Tabellen verwenden, um strukturierte Informationen klar darzustellen
Tabellen sind die beste Methode, um strukturierte Daten darzustellen. Apidog Markdown unterstützt die Standard-Markdown-Tabellensyntax und erlaubt HTML-Stile, um Tabellen professioneller und schöner zu gestalten.
Basistabelle:
| Funktion | Status | Beschreibung |
| --- | --- | --- |
| Benutzerauthentifizierung | ✅ Erledigt | Unterstützt mehrere Anmeldemethoden |
| Datensynchronisierung | ⚠️ In Bearbeitung | Nächste Woche erwartet |
| Berichtsexport | ❌ Nicht begonnen | Geplant für Q3 |Spaltenbreite anpassen: Verwenden Sie HTML-Inline-Stile, um die Spaltenbreite zu steuern und unordentliche Layouts zu vermeiden.
| <div style="width: 100px;">Funktion</div> | <div style="width: 100px;">Status</div> | <div style="width: 200px;">Beschreibungen</div> |
| --- | --- | --- |
| Benutzerauthentifizierung | ✅ Erledigt | Unterstützt mehrere Anmeldemethoden |
| Datensynchronisierung | ⚠️ In Bearbeitung | Nächste Woche erwartet |
| Berichtsexport | ❌ Nicht begonnen | Geplant für Q3 |
8. Akkordeon-Blöcke für FAQ verwenden
Akkordeon-Blöcke eignen sich ideal zum Organisieren von FAQs oder nicht-essenziellen Details. Diese Struktur ermöglicht es Lesern, Inhalte nach Bedarf zu erweitern, wodurch die Seite übersichtlich und aufgeräumt bleibt.
Akkordeon-Blöcke eignen sich besonders für FAQs, optionale Funktionen, erweiterte Konfigurationen, Fehlerbehebung usw., sodass Benutzer schnell auf wichtige Informationen zugreifen können, ohne Details zu verlieren.
Grundlegende Verwendung:
`<Accordion title="Wie setze ich mein Passwort zurück?"> 1. Klicken Sie auf der Anmeldeseite auf „Passwort vergessen“ 2. Geben Sie Ihre registrierte E-Mail-Adresse ein 3. Klicken Sie auf „E-Mail zum Zurücksetzen senden“ 4. Klicken Sie auf den Zurücksetzungslink in der E-Mail und legen Sie ein neues Passwort fest </Accordion>Standardzustand festlegen (eingeklappt):
<Accordion title="Erweiterte Einstellungen (Optional)" defaultOpen={false}> Dieser Abschnitt behandelt erweiterte, aber nicht-essenzielle Optionen für Benutzer mit speziellen Anforderungen. - Benutzerdefinierte Anfrage-Header - Proxy-Server-Einstellungen - Leistungsoptimierung </Accordion>
9. Hinweise verwenden, um wichtige Informationen hervorzuheben
Hinweise und Hervorhebungsblöcke eignen sich hervorragend, um wichtige Informationen wie Notizen, Tipps oder Warnungen zu betonen und sicherzustellen, dass Benutzer keine wichtigen Inhalte übersehen.
Hinweis:
:::tip
Dies ist ein Tipp-Hinweis
:::
:::warning
Dies ist ein Warnhinweis
:::
:::caution
Dies ist ein Vorsichtshinweis
:::
:::danger
Dies ist ein Gefahrenhinweis
:::
:::check
Dies ist ein Prüfhinweis
:::
:::info
Dies ist ein Info-Hinweis
:::
:::note
Dies ist ein Notiz-Hinweis
:::
Hervorhebungsblock:
:::highlight purple 💡
Dies ist hervorgehobener Inhalt
:::
:::highlight yellow 👋
Dies ist hervorgehobener Inhalt
:::
:::highlight orange 🚀
Dies ist hervorgehobener Inhalt
:::
:::highlight red 🌟
Dies ist hervorgehobener Inhalt
:::
:::highlight gray 🚀
Dies ist hervorgehobener Inhalt
:::
:::highlight blue 📌
Dies ist hervorgehobener Inhalt
:::
:::highlight green 🔑
Dies ist hervorgehobener Inhalt
:::
10. Hover- und Kopierfunktionen zu Begriffen hinzufügen
Mit der Tooltip-Komponente können Sie Definitionen anzeigen, wenn Sie über Text schweben.
<Tooltip tip="Dies ist ein Tipp!"> Hier schweben für einen Tipp</Tooltip>Mit der CopyToClipboard-Komponente können Sie Text durch Klicken kopieren.
<CopyToClipboard >Hier klicken, um Text zu kopieren</CopyToClipboard>Kombinieren Sie Tooltip und CopyToClipboard für "Hover-Tipp und Kopieren":
<Tooltip tip="Dies ist ein Tipp, und Sie können kopieren!"><CopyToClipboard >Hier klicken, um Text zu kopieren</CopyToClipboard></Tooltip>
Fazit
Durch die flexible Nutzung dieser Apidog Markdown-Funktionen können Sie Dokumentationen erstellen, die sowohl professionell als auch visuell ansprechend sind. Gute Dokumentation reduziert Kommunikationskosten, verbessert die Entwicklungseffizienz und unterstreicht die Professionalität und Produktqualität Ihres Teams. Eine exzellente Dokumentation ist ein wichtiger Bestandteil der Produkterfahrung und die Investition wert. Weitere Tipps finden Sie in der Apidog Markdown Dokumentation.