Développement

Modèle de spécification technique en Markdown

Ce modèle de spécification technique est un exemple traité, pas un formulaire vide. Il décrit un service de paiement et montre comment un diagramme, une formule et un exemple de code cohabitent dans un même document. Remplacez le contenu par votre propre conception et gardez la structure.

Ouvrir ce modèle dans l’éditeur

Catégorie: Développement
Style par défaut: Technique

Quand l’utiliser

Rédigez une spécification avant de construire quoi que ce soit que plusieurs personnes doivent approuver. Les ingénieurs la lisent pour revoir la conception, et les collègues produit ou qualité pour savoir ce qui sera livré. Une version PDF convient aux revues de conception, à la validation client et à toute archive où le document doit rester identique des années plus tard.

Ce qu’il contient

Une présentation avec des champs à remplir pour le projet et le responsable, suivie d’un diagramme de séquence Mermaid du flux de requêtes.
Une section sur le budget de nouvelles tentatives avec une formule TeX, et un exemple TypeScript dans un bloc de code coloré.
Un saut de page manuel avant la liste des questions ouvertes, pour qu’elle commence sur une nouvelle page.

Conseils pour un meilleur document

Placez le diagramme de flux avant les détails. Les relecteurs qui comprennent d’abord la séquence lisent le reste plus vite et posent de meilleures questions.
Gardez les questions ouvertes dans la spécification jusqu’à ce qu’on y réponde, puis déplacez chaque réponse dans la section concernée. Pour une longue spécification, ajoutez une page de couverture et un sommaire.

Aperçu du modèle

Spécification du service de paiement

Projet : Projet ou sujet Responsable : Votre nom

Aperçu

Le service de paiement reçoit une commande, débite la carte et enregistre le résultat. Les requêtes sont idempotentes pendant 24 heures.

Flux

sequenceDiagram
  participant App
  participant API
  participant Stripe
  App->>API: POST /charge
  API->>Stripe: créer PaymentIntent
  Stripe-->>API: statut
  API-->>App: reçu

Budget de réessais

Chaque client peut réessayer avec un délai exponentiel où l'attente après la tentative $n$ vaut

w_n = \min(2^n \cdot 250\,\text{ms},\ 8\,\text{s})

Exemple

export const charge = async (order: Order) => {
  const intent = await stripe.paymentIntents.create({ amount: order.total });
  return { id: intent.id, status: intent.status };
};

Questions ouvertes

Conserve-t-on les quatre derniers chiffres ?
Quelles devises en premier ?

Les champs à remplir, comme votre nom et la date, sont remplacés quand vous ouvrez le modèle dans l’éditeur.