Christian Arango
Projets de documentation

Étude de cas · Documentation multiproduit

Système documentaire SMB de Priority Commerce

J’ai conçu un système documentaire multiproduit pour Vortex, MXC, MXM et MXPOS dans ReadMe. Une architecture MDX partagée traite les modèles de page récurrents, tandis que chaque produit charge son propre paquet de référence avant la transformation d’un brouillon. Le flux convertit des sources brutes en documentation prête à réviser sans faire comme si les quatre produits étaient identiques.

Auteur
Christian Arango
Rôle
Rédacteur technique et ingénieur documentaire
Plateforme
Priority Commerce · ReadMe
Capture
Spécification du flux v2.3, 13 octobre 2026

Parcours du projet

L’évolution du travail

Ouvrez chaque étape pour suivre le problème, les décisions, la réalisation et ce qui a changé à mesure que le système gagnait en maturité.

  1. ProblèmeServir quatre produits sans effacer leurs différences

    La gamme SMB partage ReadMe et des besoins documentaires récurrents, mais chaque produit conserve son propre CSS, JavaScript, HTML et ses décisions héritées. Le système devait fournir un socle commun sans appliquer silencieusement les hypothèses du mauvais produit.

  2. Décision de systèmeSéparer le contrat MDX partagé des exceptions produit

    J’ai défini une architecture de composants prio-* pour le corps des guides, puis imposé l’identification du produit et le chargement de son paquet de référence avant toute génération. Les fichiers du produit priment en cas de conflit avec le socle.

  3. Workflow de rédactionTransformer une seule phase de découverte en MDX prêt à réviser

    Le flux repère en un seul lot les titres, liens ou médias manquants, les anomalies de numérotation et les structures véritablement nouvelles. Il génère ensuite la page avec les composants natifs de ReadMe et ne consigne que les décisions explicitement reportées par Christian.

  4. CompromisConserver un socle volontairement plus simple

    Je n’ai pas transposé à Priority les pastilles de forfait, la barre de sommaire ni les variantes par type documentaire de Recurly. Les pages partent d’une architecture de guide unique et légère ; tout nouveau composant fixe exige un besoin récurrent réel et une décision explicite.

  5. AméliorationRéinjecter dans le système les enseignements du renderer

    Le balisage des tableaux, l’espacement dans les div, la position des images, le comportement des liens et Font Awesome sont devenus des garde-fous documentés. À la version 2.3, les quatre produits SMB disposaient de leur propre paquet et d’une politique explicite pour les icônes natives.

Le problème complexe

Réutiliser l’architecture, pas le système documentaire d’une autre entreprise

Les contraintes du renderer de ReadMe sont communes ; la voix de marque et la structure produit, non. J’ai séparé les règles de plateforme des décisions de marque et placé l’identification du produit en première étape, pour que le flux ne choisisse jamais ses composants au hasard.

  1. Périmètre

    Identifier d’abord le produit

    Chaque brouillon est attribué à Vortex, MXC, MXM ou MXPOS avant la génération ; une source ambiguë devient la première question.

  2. Architecture

    Contrat partagé de composants prio-*

    Aperçus, callouts, cartes, étapes, tableaux, images, onglets de code et accordéons partagent un vocabulaire de balisage documenté.

  3. Exceptions

    Un paquet de référence réel par produit

    Chaque paquet consigne le CSS, le JavaScript, le HTML, les ressources et les exceptions délibérées qui priment sur le socle.

  4. Révision

    Des décisions humaines toujours visibles

    Le skill pose une seule fois les questions sur les lacunes importantes, garde les éléments reportés en TODO et produit du MDX à réviser, pas une publication autonome.

  • 4 produits SMB inclus dans le périmètre

  • 4 paquets de référence produit documentés

  • 1 architecture MDX partagée

Décisions et compromis

Un système partagé plus petit était plus sûr

Les choix difficiles portaient sur les limites : ce qui relève de ReadMe, de Priority et de chaque produit en particulier.

  • Aucun composant spéculatif

    Une pastille de permission, un bloc de version ou un nouveau modèle n’est ajouté qu’après qu’un vrai brouillon en a démontré le besoin.

  • Aucun héritage entre marques

    Les comportements réutilisables de ReadMe peuvent être transférés ; la voix, la terminologie et l’architecture de Recurly ne le peuvent pas.

  • Passport reste hors périmètre

    Ce système sert les quatre produits SMB et n’absorbe pas silencieusement une gamme distincte.

  • Les exceptions restent des exceptions

    Les choix hérités de Vortex, MXM et MXC sont consignés au lieu d’être « nettoyés » par des changements non approuvés.

Ce qui s’est amélioré

Le flux a gagné en précision avec les données de chaque produit

D’un socle partagé avec des hypothèses ouvertes à quatre paquets validés par audit et à des politiques explicites.

  • Charger le contexte avant de générer

    Lire d’abord le paquet du produit évite une réponse soignée fondée sur de mauvaises hypothèses d’interface ou de style.

  • Poser les questions une fois, puis terminer la page

    Une seule phase de découverte préserve l’efficacité sans masquer les informations manquantes.

  • Traiter les particularités du renderer comme un savoir de plateforme

    Une fois vérifiées entre plusieurs produits, les contraintes techniques deviennent des garde-fous communs plutôt qu’un débogage répété.

Cette étude documente l’architecture, les décisions et les paquets de référence livrés. La source ne fournit aucun résultat commercial mesuré, donc aucun n’est revendiqué.