docs: reorganize and update developer documentation
- update README.md to simplify @zen/core description - rewrite DEV.md standards section with clearer principles and remove publication section - extract publication process to new PUBLICATION.md document - rewrite REDACTION.md with simplified structure and two-context approach - bump package version in package.json
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# ZEN / START
|
||||
|
||||
CLI pour créer un projet Next.js avec le CMS @zen/core
|
||||
CLI pour créer un projet Next.js avec @zen/core
|
||||
|
||||
> [!WARNING]
|
||||
> Ce projet est en développement actif et n'est pas encore prêt pour une utilisation en production. L'API, la structure et les fonctionnalités peuvent changer à tout moment.
|
||||
|
||||
+10
-44
@@ -8,13 +8,15 @@ Pour les conventions de commit : [COMMITS.md](./dev/COMMITS.md).
|
||||
|
||||
Pour la procédure de publication du package : voir section [Publication](#publication) ci-dessous.
|
||||
|
||||
> **Contexte projet** : `@zen/start` est un CLI qui génère un projet Next.js avec le CMS `@zen/core` déjà intégré. Lors d'une assistance ou d'une revue, partez du principe que le rôle de ce package est de scaffolder — pas d'exécuter du code applicatif.
|
||||
> **Contexte projet** : `@zen/start` est un CLI qui génère un projet Next.js avec `@zen/core` déjà intégré. Partez du principe que le rôle de ce package est de scaffolder, il génère une structure de projet, il n'exécute pas de logique applicative.
|
||||
|
||||
---
|
||||
|
||||
## Standards de code
|
||||
|
||||
### Principes généraux
|
||||
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
|
||||
|
||||
**Les variables d'environnement et la documentation se mettent à jour avec le code.** Toute variable ajoutée, renommée ou supprimée doit être reflétée dans `.env.example`. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier `docs/` concerné.
|
||||
|
||||
**Une fonction, une responsabilité.** Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.
|
||||
|
||||
@@ -22,17 +24,17 @@ Pour la procédure de publication du package : voir section [Publication](#publi
|
||||
|
||||
**Les données entrantes sont suspectes.** On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.
|
||||
|
||||
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
|
||||
|
||||
**La portée des variables est minimale.** On déclare au plus près de l'usage. Pas de variables réutilisées pour deux rôles différents.
|
||||
|
||||
**ESLint passe sans avertissement.** Un warning ignoré aujourd'hui est un bug non détecté demain.
|
||||
|
||||
**Les commentaires reflètent toujours le comportement réel du code.** Un commentaire obsolète est pire qu'un commentaire absent — il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire. Un commentaire qui contredit le code est un bug de documentation.
|
||||
|
||||
---
|
||||
|
||||
## Sécurité
|
||||
|
||||
### Données entrantes
|
||||
|
||||
Toute donnée externe est considérée malveillante par défaut : arguments CLI, chemins de fichiers, noms de projet fournis par l'utilisateur. On valide et on assainit avant tout usage dans des chemins ou des commandes shell.
|
||||
**Données entrantes** : toute donnée externe est considérée malveillante par défaut. On valide côté serveur uniquement.
|
||||
|
||||
### Système de fichiers
|
||||
|
||||
@@ -44,40 +46,4 @@ const dest = path.join(targetDir, 'package.json')
|
||||
|
||||
// ✗
|
||||
const dest = targetDir + '/package.json'
|
||||
```
|
||||
|
||||
### Secrets
|
||||
|
||||
Aucun token, clé API ou credential dans le code. Le token d'authentification au registre npm est configuré localement, jamais commité.
|
||||
|
||||
---
|
||||
|
||||
## Publication
|
||||
|
||||
Le package `@zen/start` est publié sur le registre npm hébergé sur `https://git.hyko.cx`.
|
||||
|
||||
### 1. Configurer l'authentification
|
||||
|
||||
Créer un token d'accès dans Gitea (Settings → Applications → Generate Token), puis l'enregistrer localement :
|
||||
|
||||
```bash
|
||||
npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
|
||||
```
|
||||
|
||||
Remplacer `TOKEN` par le token généré.
|
||||
|
||||
### 2. Bump de version
|
||||
|
||||
Modifier `"version"` dans `package.json` en suivant [semver](https://semver.org/) :
|
||||
|
||||
| Type | Version |
|
||||
|------|---------|
|
||||
| `fix` | PATCH `1.x.X` |
|
||||
| `feat` | MINOR `1.X.0` |
|
||||
| Breaking change | MAJOR `X.0.0` |
|
||||
|
||||
### 3. Build et publish
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
# Publier le package
|
||||
|
||||
Le package `@zen/start` est publié sur le registre npm privé à `https://git.hyko.cx`.
|
||||
|
||||
### Configurer l'authentification (une seule fois)
|
||||
|
||||
Créer un token dans Gitea : **Settings → Applications → Generate Token**, puis :
|
||||
|
||||
```bash
|
||||
npm config set //git.hyko.cx/api/packages/zen/npm/:_authToken TOKEN
|
||||
```
|
||||
|
||||
### Checklist avant publication
|
||||
|
||||
- [ ] `npm audit` — aucune vulnérabilité `high` ou `critical`
|
||||
- [ ] `npm run build` — build sans erreur ni warning TypeScript
|
||||
- [ ] Version mise à jour dans `package.json`
|
||||
|
||||
### Publier
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
```
|
||||
+103
-127
@@ -1,163 +1,139 @@
|
||||
# GUIDE DE RÉDACTION
|
||||
Dernière modification : 2026-04-12
|
||||
# Rédaction
|
||||
|
||||
## La voix de l'entreprise
|
||||
|
||||
On parle comme une personne, pas comme une organisation. Direct, sans fioritures.
|
||||
|
||||
On dit **"on"** — jamais "nous sommes heureux de", jamais "notre équipe d'experts". Une seule exception : quand on cite quelqu'un nommément, on peut utiliser "je".
|
||||
|
||||
La technique est là parce qu'elle est utile, pas pour impressionner. Si une explication technique ne sert pas le lecteur, elle ne sert pas le texte.
|
||||
Ce guide s'applique à tout contenu textuel visible par l'utilisateur dans ce projet : l'interface admin, les messages d'état, les documentations dans `docs/` et les README.
|
||||
|
||||
---
|
||||
|
||||
## Ce qu'on évite absolument
|
||||
## Deux contextes, deux voix
|
||||
|
||||
**Les superlatifs vides**
|
||||
*de premier plan, leader, de pointe, best-in-class, incontournable*
|
||||
**Interface (labels, messages, descriptions)** : la plateforme rapporte ce qui s'est passé. On utilise l'impersonnel et le passif descriptif. L'utilisateur est le sujet implicite.
|
||||
|
||||
**Les promesses floues**
|
||||
*solutions sur mesure, accompagnement personnalisé, approche holistique*
|
||||
**Documentation** : on s'adresse directement au développeur qui lit. Phrases courtes, verbes actifs, ton direct.
|
||||
|
||||
---
|
||||
|
||||
## Ce qu'on évite partout
|
||||
|
||||
**Superlatifs et formules vides**
|
||||
*de premier plan, robuste, puissant, tout-en-un, intuitif, seamless*
|
||||
|
||||
**Le corporate**
|
||||
*nous nous engageons à, notre mission est de, dans une optique de, à cet effet*
|
||||
*notre plateforme vous permet de, dans une optique de, à cet effet*
|
||||
|
||||
**La sur-promesse**
|
||||
Si on ne peut pas le garantir, on ne l'écrit pas. Jamais.
|
||||
|
||||
**Les métaphores usées**
|
||||
*pont entre, clé en main, écosystème, synergies, à 360°*
|
||||
**Chevilles inutiles**
|
||||
*Ainsi, En effet, Il convient de noter que, N'hésitez pas à, Veuillez noter que*
|
||||
|
||||
**Le tiret long (—)**
|
||||
Reformuler la phrase plutôt que d'insérer une incise.
|
||||
Reformuler la phrase à la place.
|
||||
|
||||
**Les chevilles inutiles**
|
||||
*Ainsi, En effet, Il convient de noter que, N'hésitez pas à*
|
||||
|
||||
**Le passif sans raison**
|
||||
Préférer la forme active. "On a livré le projet" plutôt que "le projet a été livré".
|
||||
**La sur-promesse**
|
||||
Si on ne peut pas le garantir, on ne l'écrit pas.
|
||||
|
||||
---
|
||||
|
||||
## Formules qui marchent
|
||||
## Interface
|
||||
|
||||
**Plutôt ça :**
|
||||
> "On dit non quand c'est la bonne réponse."
|
||||
> "On pense à comment les choses vont tenir dans six mois."
|
||||
> "Ce n'est pas le bon projet pour nous. Voilà pourquoi."
|
||||
### Voix de l'interface
|
||||
|
||||
**Pas ça :**
|
||||
> "Notre approche centrée client garantit des résultats optimaux."
|
||||
> "Nous mettons notre expertise au service de vos ambitions."
|
||||
> "Une équipe passionnée à votre écoute."
|
||||
La plateforme rapporte. Elle ne dit pas "on a fait" — elle dit ce qui s'est passé.
|
||||
|
||||
**La règle d'or :** si ça pourrait figurer dans la communication d'un concurrent sans changer un mot, c'est à réécrire.
|
||||
> ✓ "Les modifications ont été enregistrées."
|
||||
> ✓ "La page a été supprimée."
|
||||
> ✗ "On a enregistré vos modifications."
|
||||
> ✗ "Nous avons bien reçu votre demande."
|
||||
|
||||
Pas de "vous" ni de "nous". L'état parle pour lui-même.
|
||||
|
||||
### Labels et boutons
|
||||
|
||||
Courts, un verbe d'action à l'infinitif, sans point.
|
||||
|
||||
> ✓ "Enregistrer", "Supprimer", "Ajouter une page"
|
||||
> ✗ "Cliquez ici pour enregistrer vos modifications"
|
||||
|
||||
Pas de majuscule à chaque mot.
|
||||
|
||||
> ✓ "Ajouter un élément"
|
||||
> ✗ "Ajouter Un Élément"
|
||||
|
||||
### Messages d'erreur
|
||||
|
||||
Nommer ce qui ne va pas. Dire quoi faire si c'est utile.
|
||||
|
||||
> ✓ "Ce champ est requis."
|
||||
> ✓ "Ce slug est déjà utilisé. Choisir un autre."
|
||||
> ✗ "Une erreur s'est produite. Veuillez réessayer."
|
||||
|
||||
Pas de code d'erreur technique si l'utilisateur n'est pas développeur.
|
||||
|
||||
### Messages de confirmation
|
||||
|
||||
Une phrase. Ce qui s'est passé, au passé passif. Sans "avec succès".
|
||||
|
||||
> ✓ "Page enregistrée."
|
||||
> ✓ "Modifications enregistrées."
|
||||
> ✓ "Élément supprimé."
|
||||
> ✗ "Vos modifications ont été enregistrées avec succès !"
|
||||
|
||||
### États vides
|
||||
|
||||
Expliquer la situation, pas juste la constater. Ajouter l'action à faire si applicable.
|
||||
|
||||
> ✓ "Aucune page pour l'instant. Créer la première."
|
||||
> ✗ "Aucun résultat trouvé."
|
||||
|
||||
### Textes d'aide et descriptions
|
||||
|
||||
Une phrase. Répondre à "pourquoi" ou "comment", pas aux deux.
|
||||
|
||||
> ✓ "Utilisé dans l'URL. Ne peut pas être modifié après publication."
|
||||
> ✗ "Le slug est un identifiant unique utilisé pour générer l'URL de la page. Il doit être en minuscules et ne peut pas contenir d'espaces ou de caractères spéciaux."
|
||||
|
||||
---
|
||||
|
||||
## Structure des textes
|
||||
## Documentation
|
||||
|
||||
### Voix de la documentation
|
||||
|
||||
On s'adresse directement au développeur. Verbes actifs, phrases courtes, sans intermédiaire.
|
||||
|
||||
> ✓ "Le registre permet d'ajouter des widgets sans toucher au core. Importer `registerWidget` et passer un composant."
|
||||
> ✗ "Le registre est un système centralisé qui permet la gestion modulaire des composants d'interface."
|
||||
|
||||
### Structure
|
||||
|
||||
- **Titre :** ce que le document permet de faire.
|
||||
- **Première phrase :** pourquoi ce document existe, à qui il s'adresse.
|
||||
- **Prérequis si nécessaire :** ce qu'il faut savoir ou avoir avant.
|
||||
- **Corps :** une idée par section, titres descriptifs.
|
||||
- **Notes :** à la fin, pas dans le milieu.
|
||||
|
||||
### Titres
|
||||
Courts, affirmatifs, sans point. Une idée, pas une liste. Pas de question rhétorique.
|
||||
|
||||
> ✓ "Zéro raccourci. Zéro compromis."
|
||||
> ✓ "On livre. On reste."
|
||||
> ✗ "Une approche rigoureuse pour des résultats durables"
|
||||
> ✗ "Pourquoi nous choisir ?"
|
||||
Descriptifs, pas génériques.
|
||||
|
||||
> ✓ "Ajouter un widget à l'admin"
|
||||
> ✗ "Configuration"
|
||||
|
||||
### Corps de texte
|
||||
Phrases courtes. Une idée par phrase. Maximum deux virgules par phrase — si on en compte plus, couper.
|
||||
|
||||
Paragraphes de trois à quatre phrases maximum. Une ligne blanche entre chaque paragraphe.
|
||||
Phrases courtes. Une idée par phrase. Paragraphes de trois à quatre phrases maximum.
|
||||
|
||||
Pas de bullet points pour des concepts. Seulement pour des listes réelles (étapes, éléments techniques, options).
|
||||
Commencer par un constat ou une situation concrète, pas par une définition.
|
||||
|
||||
### Appels à l'action
|
||||
Concrets et à l'infinitif. Pas d'exclamation.
|
||||
|
||||
> ✓ "Discuter de votre projet"
|
||||
> ✓ "Voir comment on travaille"
|
||||
> ✗ "Contactez-nous pour en savoir plus !"
|
||||
> ✗ "Passez à l'action"
|
||||
Pas de listes à puces pour des explications. Les listes servent pour les étapes, les options, les éléments techniques.
|
||||
|
||||
---
|
||||
|
||||
## Selon le format
|
||||
## Révision avant de livrer
|
||||
|
||||
### Site web
|
||||
Chaque page a une seule idée principale. Le visiteur doit comprendre l'essentiel en dix secondes. Les détails viennent après, pour ceux qui cherchent.
|
||||
|
||||
Pas de jargon en page d'accueil. Le jargon technique appartient aux pages de service, là où le lecteur s'y attend.
|
||||
|
||||
### Courriels
|
||||
Objet : concret, pas accrocheur. Dire ce dont il s'agit, pas promettre quelque chose.
|
||||
|
||||
> ✓ "Proposition — Refonte infrastructure"
|
||||
> ✗ "Une opportunité à ne pas manquer"
|
||||
|
||||
Corps du courriel : aller droit au but dès la première phrase. Pas de "j'espère que ce message vous trouve bien." Si on doit écrire plus de quatre paragraphes, se demander si c'est le bon format.
|
||||
|
||||
### Applications et interfaces
|
||||
Chaque message, étiquette ou instruction doit avoir un seul sens possible. Pas de formulation qui force l'utilisateur à interpréter.
|
||||
|
||||
Le ton reste humain, même dans un contexte technique. "Une erreur s'est produite" est mieux que "Erreur 403 — accès non autorisé" si le lecteur n'est pas développeur.
|
||||
|
||||
Les messages de confirmation, d'erreur et d'aide suivent les mêmes règles que le reste : courts, directs, actifs.
|
||||
|
||||
### Articles et billets
|
||||
Un angle précis, pas un survol. Mieux vaut un article sur un problème concis que dix paragraphes vagues.
|
||||
|
||||
Commencer par un fait, un constat ou une situation — pas par une définition.
|
||||
|
||||
> ✓ "La plupart des migrations ratent pour la même raison : on sous-estime ce qui dépend de ce qu'on déplace."
|
||||
> ✗ "La migration de données est un processus complexe qui nécessite une planification rigoureuse."
|
||||
|
||||
Terminer sur ce qu'on retient, pas sur une invitation à nous contacter.
|
||||
|
||||
### Propositions et soumissions
|
||||
Pas de section "qui sommes-nous" en ouverture. Le client le sait déjà ou s'en fout pour l'instant.
|
||||
|
||||
Commencer par le problème du client, tel qu'on l'a compris. S'il se reconnaît dans les deux premiers paragraphes, le reste a de la valeur.
|
||||
|
||||
La solution vient après le diagnostic. Jamais avant.
|
||||
|
||||
### Documents internes
|
||||
Mêmes règles de clarté que pour les textes externes. Un document interne mal écrit crée autant de confusion qu'une mauvaise communication client.
|
||||
|
||||
Titres de section descriptifs, pas génériques. "Décision retenue et raison" est mieux que "Résultats".
|
||||
|
||||
Si un document dépasse deux pages, se demander si l'information ne serait pas mieux transmise autrement.
|
||||
|
||||
### Réseaux sociaux
|
||||
Un seul message par publication. Si on a besoin d'un fil de publications pour expliquer, c'est probablement un article.
|
||||
|
||||
Le ton reste celui de l'entreprise — pas plus décontracté sous prétexte que c'est un réseau social.
|
||||
|
||||
Pas de hashtags décoratifs. Seulement ceux qui servent la découverte du contenu.
|
||||
- [ ] La première phrase dit déjà l'essentiel.
|
||||
- [ ] Chaque phrase dit quelque chose. Les phrases qui meublent sont supprimées.
|
||||
- [ ] L'interface utilise l'impersonnel. La doc s'adresse directement au lecteur.
|
||||
- [ ] Il n'y a pas de tiret long (—).
|
||||
- [ ] Les fautes sont corrigées.
|
||||
- [ ] L'utilisateur sait quoi faire ou quoi retenir après avoir lu.
|
||||
|
||||
---
|
||||
|
||||
## Parler de ce qu'on fait
|
||||
|
||||
Ne jamais affirmer qu'on est "les meilleurs" ou "différents des autres". Le montrer, pas le dire.
|
||||
|
||||
Quand on parle de ce qu'on fait, on parle de situations concrètes. Pas de généralités.
|
||||
|
||||
> ✓ "On a refusé un mandat parce que le calendrier ne tenait pas."
|
||||
> ✗ "On valorise l'honnêteté dans nos relations clients."
|
||||
|
||||
---
|
||||
|
||||
## Révision d'un texte
|
||||
|
||||
Avant de publier ou d'envoyer, se poser ces questions :
|
||||
|
||||
1. **Est-ce qu'un concurrent pourrait signer ce texte ?** Si oui, réécrire.
|
||||
2. **Est-ce qu'on promet quelque chose qu'on ne contrôle pas ?** Retirer ou nuancer.
|
||||
3. **Est-ce que chaque phrase dit quelque chose ?** Supprimer celles qui ne font que meubler.
|
||||
4. **Est-ce que le lecteur sait quoi faire ou quoi penser après ?** Si non, préciser.
|
||||
5. **A-t-on utilisé le mot "solution" ?** Le remplacer. Presque toujours.
|
||||
|
||||
---
|
||||
|
||||
*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, on l'ajuste.*
|
||||
*Ce guide évolue. Si une formule sonne faux ou si un cas n'est pas couvert, l'ajuster.*
|
||||
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@zen/start",
|
||||
"version": "1.4.1",
|
||||
"description": "CLI pour créer un projet Next.js avec le CMS @zen/core",
|
||||
"description": "CLI pour créer un projet Next.js avec @zen/core",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.hyko.cx/zen/start.git"
|
||||
|
||||
Reference in New Issue
Block a user