Écrire la documentation
Cette documentation est un site Docusaurus hébergé sur GitLab Pages, à l'adresse https://doc.formuleets.ca.
Chaque page est un fichier .mdx (Markdown) dans le dossier docs/ du dépôt
general/documentation.
Chaque push sur main met le site à jour automatiquement.
Petite correction : directement dans GitLab
Pour corriger une faute ou mettre à jour une info :
- En bas de la page à corriger, clique sur Modifier cette page.
- Fais ta modification dans l'éditeur GitLab.
- Fais un commit sur une nouvelle branche et ouvre une merge request.
Nouvelle page : en local
Installer le projet (une seule fois)
Prérequis : Node.js 20 ou plus récent et Git.
git clone https://gitlab.formuleets.ca/general/documentation.git
cd documentation
npm ci
Prévisualiser le site
npm run start
Le site s'ouvre sur http://localhost:3000/ et se recharge à chaque sauvegarde.
Où mettre ta page
| Tu écris… | Dossier |
|---|---|
| L'onboarding d'un département | docs/onboarding/departements/ (la page existe déjà, complète-la) |
| La documentation technique d'un département | docs/departements/<departement>/ (voir Documenter un département) |
| Un tuto sur un outil informatique | docs/tutos-it/ |
| Une page sur la documentation elle-même | docs/contribuer/ |
Une page ajoutée dans un dossier apparaît automatiquement dans le menu de gauche.
Pour une nouvelle section, crée un dossier avec un fichier _category_.json (voir
docs/onboarding/departements/_category_.json comme exemple).
Gabarit d'une page
---
sidebar_position: 3
title: "Mon outil : faire telle chose"
description: Une phrase qui résume ce que la page permet de faire.
---
# Mon outil : faire telle chose
Une ou deux phrases : à quoi sert l'outil et ce que tu sauras faire à la fin.
## Prérequis
- Ce qu'il faut avoir avant de commencer (accès, logiciel, réseau…).
## 1. Première étape
1. Action précise, avec les **noms des boutons** en gras.
2. Action suivante.
## 2. Deuxième étape
…
Documenter un département
Chaque département a son dossier dans docs/departements/ (software, electronique, drivetrain,
powertrain, dynamique, aero, chassis, media, it). Le fichier index.mdx du dossier est la page
d'accueil du département : décris-y le périmètre. Chaque page que tu ajoutes dans le dossier apparaît
automatiquement dans le menu et dans la liste en bas de cette page d'accueil.
Une page = un sujet. Les types de pages les plus utiles :
| Type de page | Contenu |
|---|---|
| Système | Un système ou sous-système de la voiture : fonction, choix de conception et pourquoi, calculs, emplacement des fichiers sources (CAO, code, schémas), interfaces avec les autres départements. |
| Procédure | Fabrication, assemblage, test ou entretien, en étapes numérotées. |
| Leçons apprises | Ce qui a marché ou cassé pendant une saison, et ce qu'il faut changer la prochaine fois. |
| Règlement | Les règles de la compétition qui touchent le département et comment on les respecte. |
Si un sujet demande plusieurs pages, crée un sous-dossier avec un _category_.json.
Vérifier avant de pousser
npm run build
Le build échoue si un lien interne est cassé : corrige-le avant de pousser.
Ensuite, crée une branche, commit, push et ouvre une merge request vers main.
Règles d'écriture
- En français, on tutoie le lecteur.
- Une page = un objectif. Le titre dit ce qu'on va savoir faire.
- Des étapes numérotées pour les procédures, avec les noms exacts des boutons en gras.
- Pas d'info inventée. Si tu ne connais pas une info, laisse un bloc
:::info[À compléter]. - Titre d'un encadré entre crochets :
:::warning[Mon titre]. Avec un espace (:::warning Mon titre), l'encadré ne s'affiche pas. - Jamais de mot de passe ni de secret dans la doc : ils vont dans Vaultwarden, la doc dit seulement où les trouver.
- Liens internes sans extension :
[Vaultwarden](/tutos-it/vaultwarden). - Images : dans un dossier
img/à côté de la page, puis.
Encadrés
:::tip
Astuce utile.
:::
:::info[À compléter]
Ce qui manque sur cette page.
:::
:::warning
Point d'attention.
:::
:::danger
Action irréversible ou risquée.
:::
Tu utilises Claude Code ? Un agent est prêt pour rédiger les pages à ta place : voir Rédiger avec l'agent.