Best Practices

Nachdem Sie die Markdown-Syntax beherrschen, wie schreiben Sie hochwertige, wartbare technische Dokumentation? Dieser Leitfaden bietet Best Practices von grundlegenden Standards bis zu fortgeschrittenen Tipps.

Dokumentstruktur-Design

Verzeichnisorganisation

project/
├── README.md                 # Projektübersicht
├── docs/
│   ├── index.md             # Dokumentations-Startseite
│   ├── getting-started/
│   │   ├── installation.md  # Installationsanleitung
│   │   ├── quick-start.md   # Schnellstart
│   │   └── examples.md      # Beispielcode
│   ├── api/
│   │   ├── overview.md      # API-Übersicht
│   │   ├── authentication.md # Authentifizierung
│   │   └── endpoints/       # API-Endpunkte
│   ├── guides/
│   │   ├── best-practices.md # Best Practices
│   │   └── troubleshooting.md # Fehlerbehebung
│   └── changelog.md         # Änderungsprotokoll
└── assets/
    └── images/              # Bildmaterial

Inhalts-Hierarchie

# Überschrift 1 - Dokumentthema

Kurze Einführung in den Inhalt und das Ziel dieses Dokuments.

## Überschrift 2 - Hauptabschnitte

### Überschrift 3 - Spezifische Themen

Detaillierte Inhalte und Erklärungen...

#### Überschrift 4 - Unterabschnitte

Implementierungsdetails...

##### Überschrift 5 - Zusätzliche Hinweise

Hinweise und Tipps...

> **Hinweis**: Vermeiden Sie mehr als fünf Überschriftenebenen, um eine zu komplexe Dokumentstruktur zu verhindern.

Standards für das Schreiben von Inhalten

Sprachstil

✅ Empfohlen:

1. **Verwenden Sie eine prägnante und klare Sprache**
   - Vermeiden Sie lange Sätze
   - Verwenden Sie Aktiv
   - Minimieren Sie Fachjargon

2. **Halten Sie einen konsistenten Ton bei**
   - Formal, aber freundlich
   - Benutzerorientierte Formulierungen
   - Vermeiden Sie zu technische Begriffe

3. **Geben Sie konkrete Anleitungen**
   - Verwenden Sie konkrete Zahlen und Beispiele
   - Geben Sie klare Schritte an
   - Fügen Sie erwartete Ergebnisse hinzu

❌ Vermeiden Sie:

- Vage Aussagen
- Übermäßigen Passivstil
- Fehlende notwendige Hintergründe
- Annahmen über spezifisches Vorwissen der Leser

Absätze und Formatierung

<!-- ✅ Gute Absatzstruktur -->
## Node.js installieren

Um unser Tool zu verwenden, müssen Sie zuerst Node.js installieren. Node.js ist eine JavaScript-Laufzeitumgebung, mit der Sie JavaScript auf dem Server ausführen können.

### Systemanforderungen

Stellen Sie vor der Installation sicher, dass Ihr System Folgendes erfüllt:

- Betriebssystem: Windows 10+, macOS 10.12+ oder Linux
- Arbeitsspeicher: Mindestens 4GB RAM
- Speicherplatz: Mindestens 1GB freier Speicher

### Installationsschritte

1. Besuchen Sie die [offizielle Node.js-Website](https://nodejs.org/)
2. Laden Sie das Installationsprogramm für Ihr Betriebssystem herunter
3. Führen Sie das Installationsprogramm aus und folgen Sie den Anweisungen
4. Öffnen Sie ein Terminal, um die Installation zu überprüfen:

Wenn die Versionsnummer angezeigt wird, war die Installation erfolgreich.

Installieren Sie nodejs, Sie müssen von der offiziellen Website herunterladen, dann installieren und die Version überprüfen, um den Erfolg sicherzustellen


## Standards für Codebeispiele

### Best Practices für Codeblöcke

Benutzerkonto erstellen

Das folgende Beispiel zeigt, wie Sie mit der API einen neuen Benutzer erstellen:

javascript

// Erforderliche Bibliotheken importieren
const axios = require('axios');

// API-Endpunkt konfigurieren
const API_BASE_URL = 'https://api.example.com';
const API_KEY = 'your-api-key';

// Benutzerfunktion erstellen
async function createUser(userData) {
  try {
    const response = await axios.post(`${API_BASE_URL}/users`, userData, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('User created:', response.data);
    return response.data;
  } catch (error) {
    console.error('User creation failed:', error.response.data);
    throw error;
  }
}

// Anwendungsbeispiel
const newUser = {
  name: 'Zhang San',
  email: 'zhangsan@example.com',
  role: 'user'
};

createUser(newUser);

Erwartete Ausgabe:

json

{
  "id": "12345",
  "name": "Zhang San",
  "email": "zhangsan@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

Wichtige Hinweise:

Ersetzen Sie your-api-key durch Ihren tatsächlichen API-Schlüssel
Stellen Sie die Netzwerkverbindung sicher
Bewahren Sie Ihren API-Schlüssel sicher auf; nicht ins Versionskontrollsystem einchecken

javascript

// Create user
axios.post('/users', data)

This code creates a user.


### Beispiele für die Befehlszeile

Projektbereitstellung

1. Projekt bauen

bash

# Abhängigkeiten installieren
npm install

# Tests ausführen
npm test

# Produktionsversion bauen
npm run build

2. Auf Server bereitstellen

bash

# Mit Server verbinden
ssh user@server.example.com

# Zum Projektverzeichnis wechseln
cd /var/www/myproject

# Neuesten Code ziehen
git pull origin main

# Dienst neu starten
sudo systemctl restart myproject

3. Bereitstellung überprüfen

bash

# Dienststatus prüfen
sudo systemctl status myproject

# Protokolle anzeigen
sudo journalctl -u myproject -f

Erwartete Ergebnisse:

Dienststatus zeigt active (running)
Der Besuch von https://yoursite.com zeigt die neueste Version an


## Verwaltung von Links und Referenzen

### Interne Links

Detaillierte Installationsanweisungen finden Sie im Installationsleitfaden.

Für API-Authentifizierung siehe Authentifizierungsdokumentation.

Bei Problemen siehe den Fehlerbehebungsleitfaden.

Klicken Sie hier für die Installation. Siehe: ./index.md


### Externe Links

Unsere API basiert auf dem REST-Architekturstil, und folgt den HTTP-Statuscode-Standards.

Mehr zu JWT finden Sie in der offiziellen JWT-Dokumentation und RFC 7519 Spezifikation.


### Referenzlinks

Wir unterstützen mehrere Authentifizierungsmethoden, darunter API-Schlüssel, OAuth 2.0 und JWT.

Für detaillierte Konfiguration siehe Konfigurationsleitfaden.


## Bild- und Medienoptimierung

### Richtlinien zur Bildnutzung

Benutzeroberflächenübersicht

Das folgende Bild zeigt das Hauptlayout der Anwendung:

Hauptanwendungsoberfläche

Bildhinweise:

Die obere Navigationsleiste enthält die Haupteinstiegspunkte
Die linke Seitenleiste bietet eine schnelle Navigation
Der Hauptinhaltsbereich zeigt die aktuelle Seite an
Die untere Statusleiste zeigt Systeminformationen an

Systemarchitekturdiagramm

Abbildung: Gesamtsystemarchitektur – zeigt die Beziehungen zwischen den Komponenten

Siehe Bild: Bild


### Bildorganisation und -benennung

assets/ ├── images/ │ ├── ui/ │ │ ├── dashboard-overview.png │ │ ├── user-profile-edit.png │ │ └── settings-general.png │ ├── diagrams/ │ │ ├── system-architecture.svg │ │ ├── data-flow-diagram.png │ │ └── user-workflow.png │ └── screenshots/ │ ├── installation-step-1.png │ ├── installation-step-2.png │ └── installation-complete.png

assets/ ├── images/ │ ├── img1.png │ ├── pic2.jpg │ ├── screenshot.png │ └── diagram.svg


## Prinzipien für Tabellendesign

### Datentabellen

API-Endpunktliste

Methode	Endpunkt	Beschreibung	Auth	Parameter
GET	`/api/users`	Benutzerliste abrufen	✅	`page`, `limit`, `sort`
POST	`/api/users`	Neuen Benutzer erstellen	✅	`name`, `email`, `role`
GET	`/api/users/{id}`	Bestimmten Benutzer holen	✅	`id` (Pfadparameter)
PUT	`/api/users/{id}`	Benutzerdaten aktualisieren	✅	`id`, `name`, `email`
DELETE	`/api/users/{id}`	Benutzer löschen	✅	`id` (Pfadparameter)

Hinweise:

✅ bedeutet Authentifizierung erforderlich
Alle Endpunkte erfordern einen gültigen API-Schlüssel im Anfrage-Header
Pfadparameter werden direkt in der URL angegeben
Abfrageparameter werden als ?key=value&key2=value2 übergeben

Preisplanvergleich

Funktion	Kostenlos	Pro	Enterprise
Benutzer	Bis zu 5	Bis zu 50	Unbegrenzt
Speicher	1GB	100GB	1TB
API-Aufrufe	1.000/Monat	10.000/Monat	Unbegrenzt
Support	Community	E-Mail	24/7 Dedicated
Preis	Kostenlos	99€/Monat	999€/Monat

Jetzt upgraden | Vertrieb kontaktieren


### Komplexe Datendarstellung

Serverkonfigurationsanforderungen

Server-Spezifikation	Empfohlene Konfiguration
Server-Spezifikation	Kleine Bereitstellung (<1K Benutzer)	Mittlere Bereitstellung (1K-10K Benutzer)	Große Bereitstellung (>10K Benutzer)
CPU	2 Kerne	4 Kerne	8+ Kerne
Arbeitsspeicher	4GB	8GB	16GB+
Speicher	50GB SSD	200GB SSD	500GB+ SSD
Netzwerk	100Mbps	1Gbps	10Gbps

```

Versionskontrolle und Zusammenarbeit

Dokumentversionsverwaltung

<!-- ✅ Versionsinfo am Anfang der Dokumente hinzufügen -->
---
title: API-Benutzerhandbuch
version: 2.1.0
last_updated: 2024-01-15
author: Technisches Doku-Team
---

# API-Benutzerhandbuch

> **Versionshinweis**: Dieses Dokument gilt für API v2.1.0 und höher.
> Für ältere Versionen siehe die [Archivdokumente](./archive/).

## Änderungsprotokoll

### v2.1.0 (2024-01-15)
- Benutzergruppenverwaltung hinzugefügt
- Authentifizierungsablauf verbessert
- Bekannte Probleme behoben

### v2.0.0 (2024-01-01)
- API-Architektur überarbeitet
- Authentifizierung aktualisiert
- Batch-Operationen hinzugefügt

Git-Commit-Standards

<!-- ✅ Standardformat für Commit-Nachrichten -->
docs: API-Authentifizierungsdokumentation aktualisiert

- OAuth 2.0 Beispiel hinzugefügt
- Fehler im Codebeispiel behoben
- Relevante Links aktualisiert

closes #123

<!-- ✅ Erklärung der Commit-Typen -->
Typ-Präfixe:
- docs: Dokumentationsupdate
- feat: Neue Feature-Dokumentation
- fix: Fehler in der Dokumentation beheben
- style: Formatierungsänderungen
- refactor: Dokumentstruktur überarbeiten
- test: Beispieltests hinzufügen
- chore: Build- oder Tooling-Updates

Standards für die Dokumentationszusammenarbeit

<!-- Beitragshinweis -->
## Beitragshinweis

### Einreichungsprozess

1. **Repository forken** – Erstellen Sie Ihre eigene Kopie
2. **Branch erstellen** – Für Ihre Änderungen
   ```bash
   git checkout -b docs/update-api-guide

Inhalt schreiben – Befolgen Sie die Dokumentationsstandards
Lokal testen – Stellen Sie sicher, dass die Dokumente korrekt gerendert werden
Änderungen committen – Verwenden Sie Standard-Commit-Nachrichten
PR erstellen – Beschreiben Sie Ihre Änderungen ausführlich

Code-Review-Checkliste

[ ] Inhalt korrekt
[ ] Sprache klar
[ ] Formatierungsstandards
[ ] Gültige Links
[ ] Beispielcode läuft
[ ] Bilder werden korrekt angezeigt


## Barrierefreiheit und Internationalisierung

### Barrierefreies Design

<!-- ✅ Barrierefreies Dokumentationsdesign -->
### Farbe und Kontrast

Wenn Sie Farbe zur Informationsvermittlung verwenden, geben Sie auch andere Hinweise:

::: tip Erfolg
✅ Erfolg: Vorgang abgeschlossen
:::

::: danger Fehler
❌ Fehler: Vorgang fehlgeschlagen
:::

### Alt-Text

Geben Sie für alle Bilder aussagekräftigen Alt-Text an:

![Systemarchitekturdiagramm: Zeigt den Datenfluss zwischen Client, API-Gateway, Microservices und Datenbank](/assets/images/main-interface.png)

### Tastaturnavigation

Stellen Sie sicher, dass die Dokumentstruktur die Tastaturnavigation unterstützt:

- Verwenden Sie eine logische Überschriftenhierarchie
- Stellen Sie Inhaltsverzeichnis-Links bereit
- Wichtige Links sind leicht zu finden

### Hinweise zur Internationalisierung

project/ ├── docs/ │ ├── en/ # Englische Dokumentation │ │ ├── README.md │ │ └── api/ │ ├── zh/ # Chinesische Dokumentation │ │ ├── README.md │ │ └── api/ │ └── ja/ # Japanische Dokumentation │ ├── README.md │ └── api/

Sprachversionen

Zuletzt aktualisiert: 15. Januar 2024 (de-DE) Last updated: January 15, 2024 (en-US) 最終更新日：2024年1月15日 (ja-JP)


## Leistungsoptimierung

### Optimierung des Dokumentenladens

Komplexes Systemdiagramm

<!-- ✅ Paginierungsdesign -->
### Aufteilung großer Dokumente

Teilen Sie lange Dokumente in mehrere Teile auf:

1. [Übersicht](./overview.md) – Grundkonzepte und Einführung
2. [Schnellstart](./quickstart.md) – 5-Minuten-Einstieg
3. [Tutorial](./tutorial.md) – Vollständiger Lernpfad
4. [API-Referenz](./api-reference.md) – Vollständige API-Dokumentation
5. [Beispiele](./examples.md) – Praxisbeispiele

🔍 Erweiterte Konfigurationsoptionen anzeigen

Erweiterte Konfiguration

yaml

# Detailliertes Konfigurationsbeispiel
server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem

Diese Optionen dienen der Feinabstimmung von Produktionsumgebungen...

Suchmaschinenoptimierung

<!-- ✅ Dokument-SEO-Optimierung -->
---
title: "API-Authentifizierungsleitfaden – Komplette Identitätslösung"
description: "Erfahren Sie, wie Sie OAuth 2.0, JWT und API-Schlüssel für sichere Authentifizierung verwenden. Enthält Codebeispiele und Best Practices."
keywords: ["API authentication", "OAuth", "JWT", "security", "identity"]
---

# API-Authentifizierungsleitfaden

Erfahren Sie, wie Sie API-Anfragen sicher authentifizieren und autorisieren...

## In diesem Kapitel

Dieser Leitfaden behandelt folgende Authentifizierungsmethoden:

1. [API-Schlüssel-Authentifizierung](#api-key-authentication) – Einfach und schnell
2. [OAuth 2.0](#oauth-20) – Industriestandard-Autorisierung
3. [JWT-Tokens](#jwt-tokens) – Zustandslose Authentifizierung

Qualitätssicherung

Checkliste für Inhaltsüberprüfung

<!-- 📋 Dokumentqualitäts-Checkliste -->
## Checkliste vor der Veröffentlichung

### Inhaltsqualität
- [ ] Informationen sind korrekt und vollständig
- [ ] Sprache ist klar
- [ ] Logische Struktur
- [ ] Beispielcode läuft
- [ ] Screenshots sind aktuell

### Technische Überprüfungen
- [ ] Gültige Links
- [ ] Code-Syntaxhervorhebung
- [ ] Bilder werden korrekt angezeigt
- [ ] Tabellenformatierung
- [ ] Mathematische Formeln werden korrekt gerendert

### Benutzererfahrung
- [ ] Navigation ist klar
- [ ] Suche funktioniert
- [ ] Mobile Anzeige ist angepasst
- [ ] Ladegeschwindigkeit getestet
- [ ] Barrierefreiheit geprüft

### Wartbarkeit
- [ ] Versionsinfo aktualisiert
- [ ] Änderungsprotokoll geführt
- [ ] Verwandte Dokumente synchronisiert
- [ ] Veraltete Funktionen markiert
- [ ] Migrationsanleitungen bereitgestellt

Sammlung von Benutzerfeedback

<!-- ✅ Mechanismus zur Feedbacksammlung -->
## Helfen Sie uns, uns zu verbessern

### Dokumenten-Feedback

Wenn Sie Fehler finden oder Vorschläge haben:

1. **Schnelles Feedback**: [Issue einreichen](https://github.com/example/docs/issues/new?template=doc-feedback.md)
2. **Detaillierte Diskussion**: [An der Diskussion teilnehmen](https://github.com/example/docs/discussions)
3. **Direkt bearbeiten**: [Diese Seite bearbeiten](https://github.com/example/docs/edit/main/docs/api/authentication.md)

### Diese Seite bewerten

War diese Seite hilfreich?

👍 Ja | 👎 Verbesserungswürdig | 💡 Vorschlag

### Kontakt

- 📧 Doku-Team: docs@example.com
- 💬 Technischer Support: support@example.com
- 🐦 Social: [@ExampleDocs](https://twitter.com/ExampleDocs)

Tools und Ressourcen

Dokumentqualitäts-Tools

textlint: Textkorrektur und Stilprüfung
markdownlint: Markdown-Syntaxprüfung
alex: Prüfung auf inklusive Sprache
Hemingway Editor: Lesbarkeitsanalyse

Kollaborationsplattformen

GitBook: Team-Dokumentationszusammenarbeit
Notion: Vielseitige Dokumente und Wissensmanagement
Confluence: Unternehmensdokumentation
Slab: Moderne Teamdokumentation

Analysetools

Google Analytics: Dokument-Traffic-Analyse
Hotjar: Nutzerverhaltensanalyse
Mixpanel: Nutzerinteraktions-Tracking
FullStory: Vollständige Nutzer-Sitzungsaufzeichnung

Automatisierungstools

GitHub Actions: Dokumenten-Build und Deployment
Zapier: Workflow-Automatisierung
IFTTT: Einfache Automatisierungsregeln
n8n: Open-Source-Workflow-Automatisierung

Wenn Sie diese Best Practices befolgen, können Sie hochwertige, benutzerfreundliche technische Dokumentation erstellen und eine solide Grundlage für den Erfolg Ihres Projekts schaffen.

Best Practices ​

Dokumentstruktur-Design ​

Verzeichnisorganisation ​

Inhalts-Hierarchie ​

Standards für das Schreiben von Inhalten ​

Sprachstil ​

Absätze und Formatierung ​

Installieren Sie nodejs, Sie müssen von der offiziellen Website herunterladen, dann installieren und die Version überprüfen, um den Erfolg sicherzustellen ​

Benutzerkonto erstellen ​

Projektbereitstellung ​

1. Projekt bauen ​

2. Auf Server bereitstellen ​

3. Bereitstellung überprüfen ​

Benutzeroberflächenübersicht ​

Systemarchitekturdiagramm ​

API-Endpunktliste ​

Preisplanvergleich ​

Serverkonfigurationsanforderungen ​

Versionskontrolle und Zusammenarbeit ​

Dokumentversionsverwaltung ​

Git-Commit-Standards ​

Standards für die Dokumentationszusammenarbeit ​

Code-Review-Checkliste ​

Sprachversionen ​

Erweiterte Konfiguration ​

Suchmaschinenoptimierung ​

Qualitätssicherung ​

Checkliste für Inhaltsüberprüfung ​

Sammlung von Benutzerfeedback ​

Verwandte Syntax ​

Tools und Ressourcen ​

Dokumentqualitäts-Tools ​

Kollaborationsplattformen ​

Analysetools ​

Automatisierungstools ​

Best Practices

Dokumentstruktur-Design

Verzeichnisorganisation

Inhalts-Hierarchie

Standards für das Schreiben von Inhalten

Sprachstil

Absätze und Formatierung

Installieren Sie nodejs, Sie müssen von der offiziellen Website herunterladen, dann installieren und die Version überprüfen, um den Erfolg sicherzustellen

Benutzerkonto erstellen

Projektbereitstellung

1. Projekt bauen

2. Auf Server bereitstellen

3. Bereitstellung überprüfen

Benutzeroberflächenübersicht

Systemarchitekturdiagramm

API-Endpunktliste

Preisplanvergleich

Serverkonfigurationsanforderungen

Versionskontrolle und Zusammenarbeit

Dokumentversionsverwaltung

Git-Commit-Standards

Standards für die Dokumentationszusammenarbeit

Code-Review-Checkliste

Sprachversionen

Erweiterte Konfiguration

Suchmaschinenoptimierung

Qualitätssicherung

Checkliste für Inhaltsüberprüfung

Sammlung von Benutzerfeedback

Verwandte Syntax

Tools und Ressourcen

Dokumentqualitäts-Tools

Kollaborationsplattformen

Analysetools

Automatisierungstools