Articles de documentation : Référence versionnée pour les utilisateurs existants

Un article de documentation est une référence maintenue destinée à une personne qui utilise déjà un produit, une API, un service, un appareil ou un processus opérationnel. Il répond à une question de consultation précise — ce que fait un paramètre, quelles valeurs un champ accepte, quel accès est requis, quelle version se comporte de cette manière ou où s’applique une limite — sans obliger le lecteur à passer d’abord par un argument marketing.

Son contrat est périmètre → prérequis → comportement actuel → référence exacte → exceptions → tâche connexe. La page réussit lorsqu’un utilisateur récupère le bon fait pour la bonne version et le bon rôle. Transformer chaque libellé d’interface en URL publique n’aide pas.

Questions auxquelles elle répond

La question principale est : « Que signifie ce comportement produit dans ma version et mon contexte ? » Les questions secondaires incluent :

• Cette page s’applique-t-elle à mon produit, mon plan, mon rôle, ma région, ma plateforme et ma version ?
• Qu’est-ce qui doit déjà être vrai avant que j’utilise cette fonctionnalité ou que je consulte ce champ ?
• Quelles sont les valeurs acceptées, les valeurs par défaut, les limites, les formats et les effets secondaires ?
• Quel comportement est actuel et qu’est-ce qui a changé depuis une version antérieure ?
• Quel exemple illustre la règle sans cacher d’importantes conditions ?
• Que dois-je lire ensuite si j’ai besoin d’une procédure, d’un diagnostic ou d’un historique des modifications ?
• Cette information est-elle sûre et utile dans la recherche publique, ou nécessite-t-elle un contexte authentifié ?

Quand utiliser ce type d’article

Utilisez la documentation lorsqu’une page stable doit prendre en charge des consultations répétées. Le sujet nécessite un propriétaire faisant autorité, un comportement testable et un signal de maintenance tel qu’une version, une API, un plan ou un changement d’interface.

Une page intitulée « Comment configurer les champs d’exportation » peut néanmoins être de la documentation lorsque sa valeur durable est un catalogue de champs et que les utilisateurs accèdent directement à des paramètres individuels. Inversement, « Exporter votre premier rapport » est un guide pratique lorsque le lecteur doit suivre une séquence et vérifier un fichier téléchargé. La grammaire du titre ne décide pas du format ; c’est la tâche du lecteur et la forme de la réponse qui le font.

Idéal pour ces types d’entreprises

1. SaaS. La meilleure adéquation car les rôles, plans, paramètres, intégrations, API, modèles de données et cadence de publication produisent des besoins de référence précis. La documentation doit distinguer le comportement de l’interface du comportement de l’API et les autorisations utilisateur des droits d’abonnement.
2. E-commerce. Très adapté pour l’administration des marchands, les flux de produits, les règles de paiement, les retours, les intégrations et l’utilisation post-achat. Séparez l’aide client de la documentation marchand afin qu’un acheteur n’atterrisse pas sur une référence d’implémentation.
3. Marketplaces. Pertinent lorsque les rôles acheteur, vendeur, fournisseur et administrateur voient des états différents. Chaque article doit identifier l’acteur car un même libellé peut exposer des contrôles ou des obligations différents.
4. Agences. Utile pour les portails clients, les normes de livrables, les flux de travail récurrents et les outils partagés. Publiez une référence client réutilisable publiquement uniquement lorsqu’elle n’expose pas de contrôles internes, d’identifiants ou de détails opérationnels propriétaires.
5. Services B2B. Utile pour les systèmes d’intégration, les transferts de données, les spécifications de fichiers, les états d’approbation et les portails de services. Évitez de présenter un engagement contractuel comme un fait générique de centre d’aide lorsque les conditions varient selon le compte.
6. Fabricants et entreprises industrielles. Précieux pour les contrôles, logiciels, compatibilité, configuration, enregistrements de maintenance et paramètres techniques. Les contenus critiques pour la sécurité nécessitent une révision contrôlée, une applicabilité explicite au modèle et un chemin vers le manuel faisant autorité.

Intention de recherche

L’intention de recherche est le résultat qu’une personne attend d’une requête. L’intention de la documentation est généralement navigationnelle et informationnelle : l’utilisateur connaît le produit ou l’objet et souhaite un fait exact, comme « conservation des exportations Northstar », « valeurs de statut Northstar » ou « taille de page API Northstar ». La marque, la fonctionnalité, le langage de tâche sans erreur, la version et la plateforme apparaissent souvent ensemble.

Le résultat idéal s’ouvre près de la réponse. Utilisez des titres descriptifs, des ancres stables, des valeurs acceptées et des indicateurs de version. Une déclaration extraite doit préserver sa condition : « Sur les plans Team et Enterprise, les exportations terminées restent disponibles pendant 30 jours. »

La documentation publique devrait être classée lorsqu’elle répond à une question durable sans révéler de données de compte : formats pris en charge, champs d’API publics, compatibilité, limites, signification de la configuration et comportement documenté.

La documentation ne devrait pas être classée lorsqu’elle reflète un seul libellé d’interface, duplique une page actuelle, couvre une version obsolète sans besoin continu, expose des informations sensibles ou nécessite un contexte de compte privé. Utilisez plutôt l’aide authentifiée, les conseils dans l’application, noindex, la consolidation ou un état d’archivage clair. La demande de recherche ne justifie jamais la publication de secrets ou de voies d’exploitation.

Structure de la page

Les fourchettes de mots sont des contrôles de production, pas des quotas minimum. Une référence de champ étroite peut être plus courte ; une référence de fonctionnalité versionnée peut nécessiter plus d’espace car l’applicabilité et les exceptions évitent des erreurs coûteuses.

La plupart des articles de documentation substantiels se situent entre 1 500 et 2 800 mots. N’ajoutez des détails que là où ils préviennent l’ambiguïté : périmètre, prérequis, valeur, valeur par défaut, effet secondaire, exception ou changement de version.

Éléments requis

Les lecteurs de référence parcourent le texte. Positionnez les informations d’applicabilité avant la référence afin qu’une valeur techniquement correcte ne soit pas appliquée au mauvais plan ou à la mauvaise version.

Frontmatter

Suivez la spécification du frontmatter. Sur cette spécification de type d’article, entity = "post-type-documentation-article". Sur une page de documentation produite, utilisez une valeur stable d’objet produit telle que northstar-scheduled-export-settings, et non une phrase promotionnelle comme effortless-reporting ni un numéro de version qui forcerait une nouvelle identité après chaque publication.

Utilisez schemaType = "Article". Le balisage de schéma doit décrire la page visible ; ne sélectionnez pas HowTo simplement parce qu’un exemple contient trois actions. Ajoutez des données structurées FAQ uniquement lorsque les questions et réponses visibles leur correspondent exactement. Les références d’API ou la sémantique spécifique aux logiciels peuvent être représentées ailleurs dans le modèle de données du site, mais un type de schéma plus spécifique ne devrait pas être inventé dans le frontmatter sans support de modèle.

Stockez les champs que le système de maintenance peut appliquer : domaine produit, plans, rôle, plateforme, plage de versions, date de vérification, propriétaire et URL de remplacement. lastmod signifie que le comportement a été révisé, pas qu’une faute de frappe a été corrigée. Préservez l’URL canonique à travers les versions compatibles.

Exemple complet

Cet exemple analytique fictif illustre une page de référence, pas une procédure d’exportation complète.

# Paramètres d'exportation planifiée

Les exportations planifiées créent un fichier CSV ou JSON à partir d'un rapport sauvegardé à une heure UTC fixe et le livrent à une destination approuvée. Elles sont disponibles pour les Éditeurs et les Administrateurs sur les plans Team et Enterprise. Cette référence s'applique à l'application web Northstar Analytics 6.4 et a été vérifiée le 27 août 2026.

## Avant d'utiliser cette référence

Vous avez besoin d'un rapport sauvegardé existant, d'une destination activée et d'un accès Éditeur ou Administrateur. Un Visiteur peut télécharger une exportation existante mais ne peut ni créer ni modifier une planification. Les administrateurs de destination peuvent imposer des limites supplémentaires de conservation ou de taille de fichier.

## Référence des paramètres

| Paramètre | Valeur acceptée | Défaut | Effet et contraintes |
|---|---|---|---|
| Nom | 1–80 caractères | Nom du rapport | Identifie la planification ; le modifier ne renomme pas les fichiers antérieurs. |
| Format | `csv` ou `json` | `csv` | CSV utilise l'ordre des colonnes visibles du rapport. JSON utilise des clés de champ stables. |
| Heure d'exécution | `HH:MM` en UTC | `08:00` | Les changements d'heure d'été ne déplacent pas l'heure d'exécution UTC. |
| Inclure les lignes vides | Activé ou désactivé | Désactivé | Disponible uniquement pour les rapports tabulaires ; ignoré pour les rapports récapitulatifs. |
| Conservation | 1–30 jours | 7 jours | Les fichiers existants expirent indépendamment de la planification qui les a créés. |

## Comportement et limites

Une planification lit la configuration du rapport sauvegardé au début de l'exécution. Modifier le rapport change donc les fichiers futurs mais pas les fichiers déjà générés. Mettre en pause une planification empêche de nouvelles exécutions ; cela ne supprime pas les fichiers conservés. Supprimer la destination désactive la livraison et place la planification en état « Nécessite attention ».

## Exemple

Pour un CSV quotidien nécessaire à 09:00 à Bratislava en heure standard, réglez l'heure d'exécution UTC sur `08:00`. Révisez l'heure lorsque les règles d'heure d'été changent car les planifications restent fixes en UTC.

Exemple invalide : saisir `Europe/Bratislava` dans le champ d'heure d'exécution. Le champ accepte une heure UTC, pas un identifiant de fuseau horaire.

## Différences entre versions

- Version 6.4 : les exportations JSON utilisent des clés de champ stables ; le libellé de colonne affiché n'est plus la clé.
- Versions 6.1–6.3 : les clés JSON suivent les libellés de colonne affichés. Les intégrations existantes doivent être vérifiées avant la mise à niveau.
- Avant 6.1 : l'exportation JSON planifiée n'est pas disponible. Utilisez CSV ou passez à une version prise en charge.

## Si une exportation n'arrive pas

N'ajoutez pas de correctifs spéculatifs ici. Ouvrez le guide de dépannage « L'exportation planifiée n'est pas arrivée », qui vérifie l'état de la planification, l'autorisation de la destination, les limites de fichiers et les incidents de service dans l'ordre diagnostique.

## Tâches connexes

- Créer votre première exportation planifiée — configuration ordonnée et vérification de succès
- Dépanner une exportation planifiée manquante — diagnostic basé sur les symptômes
- Notes de version de Northstar Analytics 6.4 — changements de comportement et note de migration

## Registre de vérification

Vérifié sur l'application web 6.4 par le responsable du produit Reporting le 27 août 2026. À réviser lorsque les autorisations, formats, conservation, planification ou le comportement de la destination changent.

Galerie de designs

Utilisez des paramètres, limites, rôles et faits de version identiques à travers les variantes afin que la revue de design mesure la rapidité de récupération plutôt que les différences de texte.

Liste de contrôle qualité

Un article de documentation est prêt uniquement lorsque chaque affirmation applicable est vraie :

• L’ouverture nomme l’objet exact et donne le comportement actuel avant le contexte ou les avantages.
• L’applicabilité du produit, du plan, du rôle, de la région, de la plateforme et de la version est explicite là où elle modifie la réponse.
• Les prérequis apparaissent avant les paramètres ou exemples qui en dépendent.
• Chaque terme technique est défini à sa première utilisation, exprimé via un libellé d’interface familier ou lié à sa définition canonique.
• Les champs, valeurs, valeurs par défaut, unités, formats, limites et effets secondaires proviennent d’une source fiable ou d’un test produit vérifié.
• Les tableaux de référence utilisent des dimensions cohérentes ; les cellules vides ne cachent pas de valeurs par défaut ou d’exceptions inconnues.
• Les exemples indiquent les conditions qui les rendent valides et incluent un exemple invalide ou limite lorsque la confusion est probable.
• Les avertissements apparaissent avant un comportement destructeur, irréversible, sensible à la sécurité, coûteux ou modifiant les autorisations.
• Les captures d’écran incluent une version de capture et un équivalent textuel ; l’image n’est pas la seule source d’une valeur ou d’une instruction.
• Les titres et ancres correspondent aux noms recherchés par les utilisateurs et restent stables pour les liens profonds.
• Les différences matérielles de version indiquent la plage concernée, le remplacement actuel et la conséquence de migration.
• La date de vérification reflète une révision comportementale, et une équipe ou un rôle nommé est responsable de la prochaine révision.
• Les procédures, diagnostics et historiques de versions renvoient vers les pages sœurs canoniques au lieu d’être dupliqués incomplètement.
• L’indexation publique est intentionnelle ; les contenus obsolètes, en double, privés et sensibles à la sécurité bénéficient d’un traitement de recherche approprié.
• Les enregistrements FAQ correspondent aux réponses visibles, et le CTA respecte la prochaine tâche d’un lecteur en phase d’assistance.

Erreurs courantes

Rédiger une page de présentation de fonctionnalité pour un utilisateur existant. « Débloquez des exportations puissantes » retarde le fait dont le lecteur a besoin. Commencez par le comportement, l’applicabilité et les contraintes ; le contenu vantant les avantages n’a sa place que là où il clarifie l’objectif.

Transformer chaque tâche en documentation. Une configuration en 20 étapes enfouie sous une liste de champs ne sert ni la consultation ni l’achèvement. Séparez la procédure ordonnée en un guide pratique et liez-la depuis le prérequis ou la section de tâches connexes concerné.

Publier une page par libellé d’interface. Les pages superficielles se chevauchent et multiplient la maintenance. Regroupez les champs autour d’un objet produit stable, à moins qu’un paramètre n’ait un comportement distinct.

Utiliser « dernière version » comme version. La dernière version change. Indiquez la version testée, la plage prise en charge, la plateforme et la date de vérification, puis mettez-les à jour via le processus de publication.

Garder les pages anciennes et nouvelles indexables sans délimitation. Consolidez les comportements compatibles ; sinon, étiquetez l’ancienne version, créez un lien vers la page actuelle et contrôlez l’indexation intentionnellement.

Cacher les prérequis dans les erreurs. Si seuls les Administrateurs peuvent modifier un champ, dites-le avant la référence. Ne laissez pas un Visiteur découvrir la limite de rôle après avoir suivi un exemple.

Copier les captures d’écran au lieu du comportement. Une capture est une preuve d’un état d’interface, pas la spécification. Rédigez les libellés, chemins, valeurs et conditions dans un texte accessible et enregistrez la version capturée.

Simuler la fraîcheur. Changer la date sans retester le comportement donne l’impression que la page est plus sûre tout en augmentant le risque. Mettez à jour le registre de vérification uniquement après que son propriétaire a vérifié les affirmations applicables.

Laisser la recherche publique exposer des détails internes. Les chemins d’escalade internes, les secrets, les identifiants clients, les instructions d’exploitation et les comportements non annoncés ne deviennent pas sûrs parce qu’ils réduisent l’effort d’assistance. Séparez l’aide publique de la connaissance authentifiée et interne.

Liens internes

Créez un lien vers le haut vers types d’articles SEO lorsque l’auteur peut avoir besoin d’une forme de réponse différente. Créez un lien depuis un prérequis de documentation vers le guide pratique canonique uniquement si le lecteur doit d’abord accomplir cette tâche. Créez un lien depuis un état d’erreur vers le dépannage plutôt que d’insérer une liste générique de correctifs. Créez un lien depuis une différence de version vers l’événement de version lorsque l’historique des modifications ajoute du contexte ; les notes de version doivent renvoyer vers la documentation actuelle comme source de vérité durable.

Organisez les liens autour des objets produit et de l’état du lecteur. Gardez un lien spécifique à côté de l’énoncé qui crée la prochaine question plutôt que de vous fier à une longue liste d’articles connexes.

Une seule page canonique actuelle devrait détenir le comportement stable. Ne conservez les pages de version que pour des comportements matériellement différents dont les utilisateurs ont encore besoin, et rendez cette distinction explicite. Utilisez des ancres stables comme #retention, pas #table-2.

Comment mesurer les résultats

Mesurez si les utilisateurs récupèrent la réponse correcte pour leur version. Le trafic seul est une preuve faible : une augmentation peut refléter un produit défectueux ou une réponse obsolète.

Enregistrez les requêtes cibles, l’URL de classement, l’indexabilité, les versions prises en charge, les recherches d’assistance, les sorties vers les tâches connexes et un événement produit approprié. Puis examinez :

• les impressions de recherche et les visites qualifiées pour les requêtes sur les objets produit, champs, limites, syntaxe, rôles et versions ;
• les affinements de recherche internes, les recherches sans résultat et les recherches répétées qui révèlent une terminologie manquante ;
• l’engagement avec les sections ancrées plutôt qu’un temps indifférencié sur la page ;
• les clics vers la bonne destination de configuration, dépannage, version ou assistance ;
• les contacts d’assistance dont la question aurait dû recevoir une réponse par la page, segmentés par version et rôle lorsque la vie privée le permet ;
• les citations qui préservent la valeur avec son plan, sa version, son unité ou son prérequis ;
• les URL obsolètes qui apparaissent encore dans les résultats ou sont citées après consolidation ou retrait ;
• les modifications de documentation causées par les versions, les changements d’interface, les changements de politique et les cas d’assistance récurrents.

Utilisez le suivi des prompts pour les questions de consultation de marque et les variantes de version. Utilisez l’ intelligence des sources et citations pour voir quelle URL un moteur de réponse cite et si son résumé préserve les conditions. Ouvrez le AmICited Cockpit pour comparer les URL citées, la visibilité, l’activité organique d’atterrissage et l’événement produit ou support choisi sur la même fenêtre d’observation.

Suivez comment nous mesurons les résultats pour séparer la découverte, la représentation, l’engagement, la progression des tâches et la rétention. Annotez les versions et incidents avant d’interpréter les mouvements. Une réponse à zéro clic fonctionne uniquement lorsqu’elle préserve la valeur actuelle et ses conditions.

FAQ

Foire aux questions