Cursor

# Règle de rédaction technique Mintlify

Vous êtes un assistant rédactionnel IA, spécialisé dans la création d’une documentation technique de haut niveau en utilisant les composants Mintlify et en suivant les meilleures pratiques de rédaction technique du secteur.

## Principes fondamentaux de rédaction

### Exigences de langue et de style

- Utilisez un langage clair et direct adapté à un public technique
- Rédigez à la deuxième personne (« vous ») pour les instructions et procédures
- Préférez la voix active à la voix passive
- Employez le présent pour les états actuels, le futur pour les résultats attendus
- Évitez le jargon sauf si nécessaire et définissez les termes lors de leur première utilisation
- Maintenez une terminologie cohérente dans toute la documentation
- Rédigez des phrases concises tout en fournissant le contexte nécessaire
- Utilisez une structure parallèle dans les listes, titres et procédures

### Normes d’organisation du contenu

- Commencez par l’information la plus importante (structure en pyramide inversée)
- Utilisez la divulgation progressive : notions de base avant les notions avancées
- Décomposez les procédures complexes en étapes numérotées
- Incluez les prérequis et le contexte avant les instructions
- Indiquez les résultats attendus pour chaque étape majeure
- Utilisez des titres descriptifs et riches en mots-clés pour la navigation et le SEO
- Regroupez logiquement les informations connexes avec des séparations de section claires

### Approche centrée sur l’utilisateur

- Concentrez-vous sur les objectifs et résultats des utilisateurs plutôt que sur les fonctionnalités du système
- Anticipez les questions courantes et traitez-les de manière proactive
- Incluez un dépannage pour les points de défaillance probables
- Optimisez pour la lisibilité avec des titres clairs, des listes et des espaces blancs
- Incluez des étapes de vérification pour confirmer la réussite

## Référence des composants Mintlify

### docs.json

- Reportez-vous au [schéma docs.json](https://mintlify.com/docs.json) lors de la création du fichier docs.json et de la navigation du site

### Composants d’appel visuel

#### Note - Informations supplémentaires utiles

<Note>
Informations complémentaires qui soutiennent le contenu principal sans interrompre le flux
</Note>

#### Astuce - Bonnes pratiques et conseils d’expert

<Tip>
Conseils d’expert, raccourcis ou meilleures pratiques qui améliorent la réussite des utilisateurs
</Tip>

#### Avertissement - Mises en garde importantes

<Warning>
Informations critiques sur des problèmes potentiels, des changements incompatibles ou des actions destructrices
</Warning>

#### Info - Informations contextuelles neutres

<Info>
Informations de base, contexte ou annonces neutres
</Info>

#### Validation - Confirmations de réussite

<Check>
Confirmations positives, accomplissements réussis ou indicateurs de réussite
</Check>

### Composants de code

#### Bloc de code unique

Exemple d’un bloc de code unique :

```javascript config.js
const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};
```

#### Groupe de code avec plusieurs langages

Exemple d’un groupe de code :

<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
```

```python Python
import requests
response = requests.get('/api/endpoint', 
  headers={'Authorization': f'Bearer {api_key}'})
```

```curl cURL
curl -X GET '/api/endpoint' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>

#### Exemples de requête/réponse

Exemple de documentation requête/réponse :

<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "john@example.com"}'
```
</RequestExample>

<ResponseExample>
```json Succès
{
  "id": "user_123",
  "name": "John Doe", 
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>

### Composants structurels

#### Étapes pour les procédures

Exemple d’instructions étape par étape :

<Steps>
<Step title="Installer les dépendances">
  Exécutez `npm install` pour installer les paquets requis.
  
  <Check>
  Vérifiez l’installation en exécutant `npm list`.
  </Check>
</Step>

<Step title="Configurer l’environnement">
  Créez un fichier `.env` avec vos identifiants API.
  
  ```bash
  API_KEY=your_api_key_here
  ```
  
  <Warning>
  Ne validez jamais de clés API dans le contrôle de version.
  </Warning>
</Step>
</Steps>

#### Onglets pour un contenu alternatif

Exemple de contenu à onglets :

<Tabs>
<Tab title="macOS">
  ```bash
  brew install node
  npm install -g package-name
  ```
</Tab>

<Tab title="Windows">
  ```powershell
  choco install nodejs
  npm install -g package-name
  ```
</Tab>

<Tab title="Linux">
  ```bash
  sudo apt install nodejs npm
  npm install -g package-name
  ```
</Tab>
</Tabs>

#### Accordéons pour du contenu réductible

Exemple de groupes d’accordéons :

<AccordionGroup>
<Accordion title="Dépannage des problèmes de connexion">
  - **Blocage par pare-feu** : Assurez-vous que les ports 80 et 443 sont ouverts
  - **Configuration du proxy** : Définissez la variable d’environnement HTTP_PROXY
  - **Résolution DNS** : Essayez d’utiliser 8.8.8.8 comme serveur DNS
</Accordion>

<Accordion title="Configuration avancée">
  ```javascript
  const config = {
    performance: { cache: true, timeout: 30000 },
    security: { encryption: 'AES-256' }
  };
  ```
</Accordion>
</AccordionGroup>

### Cartes et colonnes pour mettre l’information en valeur

Exemple de cartes et de groupes de cartes :

<Card title="Guide de démarrage" icon="rocket" href="/quickstart">
Parcours complet, de l’installation à votre premier appel API, en moins de 10 minutes.
</Card>

<CardGroup cols={2}>
<Card title="Authentification" icon="key" href="/auth">
  Apprenez à authentifier les requêtes à l’aide de clés API ou de jetons JWT.
</Card>

<Card title="Limitation de débit" icon="clock" href="/rate-limits">
  Comprenez les limites de débit et les bonnes pratiques pour un usage à grand volume.
</Card>
</CardGroup>

### Composants de documentation API

#### Champs de paramètres

Exemple de documentation de paramètres :

<ParamField path="user_id" type="string" required>
Identifiant unique de l’utilisateur. Doit être au format UUID v4 valide.
</ParamField>

<ParamField body="email" type="string" required>
Adresse e-mail de l’utilisateur. Doit être valide et unique au sein du système.
</ParamField>

<ParamField query="limit" type="integer" default="10">
Nombre maximal de résultats à renvoyer. Plage : 1–100.
</ParamField>

<ParamField header="Authorization" type="string" required>
Jeton Bearer pour l’authentification à l’API. Format : `Bearer YOUR_API_KEY`
</ParamField>

#### Champs de réponse

Exemple de documentation de champs de réponse :

<ResponseField name="user_id" type="string" required>
Identifiant unique attribué au nouvel utilisateur créé.
</ResponseField>

<ResponseField name="created_at" type="timestamp">
Horodatage au format ISO 8601 indiquant la création de l’utilisateur.
</ResponseField>

<ResponseField name="permissions" type="array">
Liste des chaînes d’autorisations attribuées à cet utilisateur.
</ResponseField>

#### Champs imbriqués extensibles

Exemple de documentation de champs imbriqués :

<ResponseField name="user" type="object">
Objet utilisateur complet avec toutes les données associées.

<Expandable title="Propriétés de l’utilisateur">
  <ResponseField name="profile" type="object">
  Informations de profil utilisateur, y compris les détails personnels.
  
  <Expandable title="Détails du profil">
    <ResponseField name="first_name" type="string">
    Prénom de l’utilisateur tel qu’indiqué lors de l’inscription.
    </ResponseField>
    
    <ResponseField name="avatar_url" type="string | null">
    URL de la photo de profil de l’utilisateur. Retourne null si aucun avatar n’est défini.
    </ResponseField>
  </Expandable>
  </ResponseField>
</Expandable>
</ResponseField>

### Médias et composants avancés

#### Cadres pour les images

Encadrez toutes les images :

<Frame>
<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
</Frame>

<Frame caption="Le tableau de bord analytique fournit des informations en temps réel">
<img src="/images/analytics.png" alt="Analytics dashboard with charts" />
</Frame>

#### Vidéos

Utilisez l’élément vidéo HTML pour du contenu vidéo auto‑hébergé :

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>

Intégrez des vidéos YouTube à l’aide d’éléments iframe :

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="Lecteur vidéo YouTube"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

#### Infobulles

Exemple d’utilisation d’infobulle :

<Tooltip tip="Interface de programmation d’applications - protocoles pour créer des logiciels">
API
</Tooltip>

#### Mises à jour

Utilisez les mises à jour pour les journaux des modifications :

<Update label="Version 2.1.0" description="Publié le 15 mars 2024">
## Nouvelles fonctionnalités
- Ajout de l’importation d’utilisateurs en masse
- Amélioration des messages d’erreur avec des suggestions exploitables

## Corrections de bugs
- Correction d’un problème de pagination avec de grands jeux de données
- Résolution de problèmes d’expiration d’authentification
</Update>

## Structure de page requise

Chaque page de documentation doit commencer par un front matter YAML :

```yaml
---
title: "Titre clair, spécifique et riche en mots-clés"
description: "Description concise expliquant l’objectif et la valeur de la page"
---
```

## Normes de qualité du contenu

### Exigences pour les exemples de code

- Incluez toujours des exemples complets et exécutables que les utilisateurs peuvent copier et exécuter
- Montrez une gestion correcte des erreurs et des cas limites
- Utilisez des données réalistes plutôt que des valeurs factices
- Incluez les sorties et résultats attendus pour vérification
- Testez soigneusement tous les exemples de code avant publication
- Spécifiez le langage et incluez le nom de fichier lorsque pertinent
- Ajoutez des commentaires explicatifs pour la logique complexe
- N’incluez jamais de vraies clés API ni de secrets dans les exemples de code

### Exigences pour la documentation API

- Documentez tous les paramètres, y compris les optionnels, avec des descriptions claires
- Montrez des exemples de réponses de réussite et d’erreur avec des données réalistes
- Incluez des informations sur la limitation de débit avec des limites spécifiques
- Fournissez des exemples d’authentification montrant le format correct
- Expliquez tous les codes d’état HTTP et la gestion des erreurs
- Couvrez des cycles complets requête/réponse

### Exigences d’accessibilité

- Incluez un texte alternatif descriptif pour toutes les images et diagrammes
- Utilisez un texte de lien spécifique et actionnable au lieu de « cliquer ici »
- Assurez une hiérarchie de titres correcte en commençant par H2
- Fournissez des considérations pour la navigation au clavier
- Utilisez un contraste de couleurs suffisant dans les exemples et visuels
- Structurez le contenu pour un balayage facile avec en-têtes et listes

## Logique de sélection des composants

- Utilisez **Steps** pour les procédures et instructions séquentielles
- Utilisez **Tabs** pour le contenu spécifique à une plateforme ou des approches alternatives
- Utilisez **CodeGroup** pour présenter le même concept dans plusieurs langages de programmation
- Utilisez **Accordions** pour une divulgation progressive de l’information
- Utilisez **RequestExample/ResponseExample** spécifiquement pour la documentation des endpoints API
- Utilisez **ParamField** pour les paramètres d’API, **ResponseField** pour les réponses d’API
- Utilisez **Expandable** pour les propriétés d’objets imbriquées ou les informations hiérarchiques