💻 Développement

technical-writing-guide

Rédaction technique claire pour documentation, ADR et RFC.

⚡ Installation & lancement en 1 commande

Copiez-collez dans votre terminal : le skill s'installe dans ~/.claude/skills et Claude Code se lance directement dessus.

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/khalilbenaz/claude-skills-collection/main/install.sh | sh -s -- technical-writing-guide --launch
Windows (PowerShell)
iex "& { $(iwr -useb https://raw.githubusercontent.com/khalilbenaz/claude-skills-collection/main/install.ps1) } technical-writing-guide -Launch"

🚀 Déjà installé ?

claude "/technical-writing-guide"

Ou tapez /technical-writing-guide dans une session Claude Code, ou décrivez simplement votre besoin — le skill se déclenche automatiquement via le skill-router.

🔑 Déclencheurs automatiques

Le skill s'active automatiquement quand votre demande contient :

documentation techniquetechnical writingrédiger une docADRRFCarchitecture decision recordcomment documenterREADME

📦 Installation manuelle

git clone https://github.com/khalilbenaz/claude-skills-collection.git cp -r claude-skills-collection/dev-skills/technical-writing-guide ~/.claude/skills/

Source : dev-skills/technical-writing-guide

📖 Manuel

Technical Writing Guide

Workflow

  1. Identifier l'audience : Déterminer qui lira le document (développeurs, ops, management, utilisateurs finaux). Adapter le niveau de détail, le vocabulaire et la structure en conséquence. Un README pour devs peut être technique ; une doc pour utilisateurs finaux doit être simple et guidée.
  1. Structurer le document : Appliquer une structure claire selon le type : titre explicite, contexte (pourquoi ce doc existe), problème adressé, solution proposée, alternatives envisagées, conséquences et décisions prises. Utiliser des titres hiérarchiques (H1 → H2 → H3).
  1. Rédiger un README efficace : Inclure les badges (CI status, coverage, version), une description courte, les prérequis, les étapes d'installation pas-à-pas, des exemples d'usage concrets, la référence API, un guide de contribution (CONTRIBUTING.md) et la licence. Le README est la vitrine du projet.
  1. Créer des Architecture Decision Records (ADR) : Format standard : titre numéroté (ADR-001), statut (proposed/accepted/deprecated/superseded), contexte (situation actuelle), décision prise, conséquences (avantages et inconvénients). Stocker dans /docs/adr/. Lier les ADR entre eux quand ils se succèdent.
  1. Documenter les APIs : Couvrir chaque endpoint avec méthode HTTP, URL, paramètres (path, query, body), exemples de requête/réponse, codes d'erreur détaillés, mécanismes d'authentification et rate limits. Préférer OpenAPI/Swagger pour la génération automatique et la testabilité.
  1. Intégrer des diagrammes : Utiliser le modèle C4 (Context, Containers, Components, Code) pour l'architecture. Ajouter des sequence diagrams pour les flux complexes, des flowcharts pour les algorithmes, des ERD pour les bases de données. Outils recommandés : Mermaid (intégré GitHub/GitLab), PlantUML, draw.io. Versionner les sources des diagrammes, pas seulement les images.
  1. Garantir style et clarté : Phrases courtes (max 20 mots). Voix active ("Le service envoie une requête" vs "Une requête est envoyée"). Définir tout terme technique à sa première occurrence. Ajouter des exemples concrets et des cas d'usage réels. Éviter le jargon inutile. Relire à voix haute pour détecter les formulations lourdes.
  1. Assurer la maintenance : Adopter docs-as-code (documentation dans le même repo que le code). Versionner avec le code. Ajouter des checks automatiques (liens cassés, orthographe, freshness). Définir un owner par document. Planifier des revues périodiques (tous les 3-6 mois). Marquer les docs obsolètes clairement avec une bannière et un lien vers la version à jour.

Règles