Comment planifier un ensemble de documentation logicielle basé sur des captures d'écran

Un ensemble de documentation avec des captures d'écran est facile à lancer et difficile à maintenir. Chaque image est une copie de l'interface à un moment donné, et l'interface continue d'évoluer. La planification avant la capture détermine si l'ensemble survit à la première refonte.

Cet article explique comment structurer l'ensemble, définir des règles pour les captures d'écran et les produire sur Mac avec Temposhot. Un exemple concret traverse toutes les sections : une petite application web de facturation avec cinq domaines fonctionnels et un rédacteur technique qui gère aussi le support.

Lister les questions auxquelles les lecteurs doivent répondre

Recueillez des questions réelles avant de définir les pages. Les sources utiles sont les tickets de support, les appels commerciaux, les sessions d'onboarding, les fils de discussion internes et les termes de recherche de votre documentation actuelle.

Rédigez chaque question avec les mots du lecteur :

• « Comment inviter un collaborateur ? »
• « Pourquoi mon export est-il vide ? »
• « Que signifie le statut Sync ? »
• « Quel forfait inclut les journaux d'audit ? »

Regroupez les doublons. La liste obtenue définit le périmètre de l'ensemble. Ce qui n'y figure pas peut attendre.

Exemple concret : des tickets à la liste de questions

L'équipe facturation a exporté 240 tickets de support des 90 derniers jours. La lecture seule des objets et du premier message client a pris environ deux heures. Après fusion des doublons, 52 questions distinctes sont restées.

Neuf questions revenaient plus de dix fois chacune. Ces neuf questions couvraient près de la moitié de tous les tickets : elles ont donc fixé l'ordre de travail. Les 43 autres questions ont été placées dans un backlog trié par domaine : factures, clients, paiements, paramètres et facturation.

Conserver les mots utilisés par les lecteurs

Gardez la formulation du lecteur à côté de chaque question, même si elle ne correspond pas au libellé de l'interface. Un client qui écrit « supprimer une carte » ne cherchera pas « Moyens de paiement ». Le titre de la page doit utiliser le libellé du produit, et la première phrase peut reprendre le terme du lecteur pour que la recherche trouve les deux.

Notez aussi le contexte de chaque question : le forfait, le rôle et l'appareil. « Comment rembourser une facture ? » posée par un titulaire de compte et la même question posée par un rôle lecteur mènent à des pages différentes. La première est un guide de tâche, la seconde une page de dépannage sur les autorisations manquantes.

Retirer les questions que la documentation ne peut pas résoudre

Certains tickets décrivent un bug ou une fonctionnalité absente. Une page qui explique un bug devient une solution de contournement qui survit au correctif. Dans l'exemple, 6 signalements de bug ont été écartés pendant la fusion, avant le décompte de 52, et transmis à l'équipe produit plutôt qu'au backlog de documentation.

D'autres questions viennent d'un libellé peu clair. Si dix lecteurs demandent ce que signifie « Sync », une page de référence aide, mais un libellé plus clair aide davantage. Transmettez aussi ces questions à l'équipe produit, et rédigez la page seulement si le libellé est conservé.

Attribuer un type de page à chaque question

Des questions différentes demandent des formats de page différents. Les mélanger rend les pages longues et difficiles à parcourir.

Type de page	Répond à	Captures d'écran
Guide de tâche	« Comment faire X »	Une par étape
Référence	« Que signifie X »	Une vue d'ensemble annotée par écran
Dépannage	« Pourquoi X a échoué »	L'état d'erreur et la correction
Concept	« Comment fonctionne X »	Schémas, peu ou pas de captures

Attribuez un type à chaque question de la liste. La plupart des questions sur le produit aboutissent à des guides de tâche.

Compter les captures avant de rédiger

Le type de page indique le nombre d'images qu'une page contiendra. Multipliez ce nombre par le nombre de pages : le résultat est le nombre d'images à mettre à jour après chaque refonte. Ce décompte est utile avant d'ouvrir un outil de capture.

Dans l'exemple, 31 des 52 questions sont devenues des guides de tâche comptant en moyenne 7 étapes. Douze sont devenues des pages de dépannage avec 2 images chacune, 6 des pages de référence avec 1 vue d'ensemble annotée chacune, et 3 des pages de concept sans capture d'écran.

Les 247 images représentent la charge réelle de maintenance de l'ensemble. La refonte d'un domaine qui touche un cinquième d'entre elles implique environ 50 remplacements, soit une ou deux journées de travail. Connaître ce chiffre rend la politique de captures ci-dessous plus facile à justifier.

Scinder les questions qui mélangent plusieurs types

Certaines questions portent deux types à la fois. « Pourquoi mon export est-il vide et comment le corriger ? » est une page de dépannage qui renvoie à un guide de tâche. Rédigez la page de dépannage avec l'erreur et sa cause, puis renvoyez au guide de tâche pour la procédure complète.

Définir une politique de captures d'écran

Définissez une fois l'apparence des captures et notez-la. Un ensemble cohérent paraît maintenu et se met à jour plus vite.

• Taille de fenêtre : une taille fixe pour toutes les captures. La cible Specific Window dans Action Capture garde la même fenêtre pendant toute une exécution.
• Thème et langue : clair ou sombre, et une seule langue d'interface.
• Données : comptes de test et noms fictifs uniquement.
• Recadrage : la fenêtre ou le panneau, jamais le bureau entier. Utilisez Framing avec Focus on action au niveau Balanced ou Close.
• Repères : un marqueur de clic ou une flèche par image, une seule couleur d'accent.
• Format : PNG pour le texte de l'interface, WebP si votre site exige des fichiers plus légers.

Décidez aussi où les captures ne sont pas nécessaires : un réglage à un seul champ, une étape dont le libellé figure dans le texte, un écran qui change à chaque version.

Traduire la politique en réglages de capture

Une politique écrite ne sert que si les réglages de capture la reproduisent. Configurez Action Capture une fois : les valeurs sont enregistrées sur le Mac pour chaque exécution suivante. L'équipe de l'exemple a utilisé les réglages ci-dessous pour les 31 guides de tâche.

Specific Window garde une seule fenêtre de navigateur comme cible pendant toute l'exécution, de sorte que chaque étape ait la même largeur en pixels. Désactivez Include toolbar in captures, sinon la barre d'outils flottante apparaît dans les images de documentation. Gardez Capture outside clicks désactivé, sauf si la tâche utilise une seconde fenêtre, comme un gestionnaire de mots de passe.

Définir les niveaux de cadrage par type de page

Le cadrage ne modifie pas l'image source : la politique peut donc fixer un niveau tout en autorisant des exceptions. Les guides de tâche utilisent Balanced (niveau 3) par défaut, ce qui laisse assez de page pour que le lecteur trouve la commande. Les petits contrôles, comme un interrupteur dans une longue liste de paramètres, passent à Close (niveau 4).

Les vues d'ensemble de référence n'utilisent aucun cadrage. Elles montrent la fenêtre entière avec des libellés numérotés, car l'objectif est de nommer chaque zone. Step Numbers est un outil Pro : sur le forfait gratuit, le même résultat demande des libellés Text placés à la main.

Définir les cas où ne pas capturer

Chaque image représente une mise à jour future, donc la politique doit aussi lister les cas sans capture d'écran. L'équipe de l'exemple a renoncé aux images pour les étapes où la seule action consistait à saisir une valeur dans un champ étiqueté. Elle a aussi renoncé aux notifications de confirmation qui disparaissent au bout de 3 secondes, et a décrit le message en texte.

Si aucun de ces cinq points ne s'applique, rédigez l'étape en texte seul. Dans l'exemple, cette règle a supprimé 38 des 217 images prévues pour les guides de tâche avant le début des captures.

Préparer un compte de test unique pour chaque capture

Les captures issues de comptes différents affichent des noms, des totaux et des dates différents, et les lecteurs le remarquent. L'équipe de l'exemple a créé un espace de travail de test avec 3 clients, 12 factures et 2 moyens de paiement, tous avec des noms fictifs. Chaque guide part de cet espace, de sorte que le même nom de client apparaisse sur toutes les pages.

Réinitialisez les données de test avant chaque exécution. Un guide enregistré après la suppression d'une facture par un autre guide affichera 11 factures au lieu de 12, et la mise à jour suivante ne correspondra pas. Écrivez les étapes de réinitialisation en haut du document de politique pour qu'un autre rédacteur puisse les reproduire.

Réglez la fenêtre du navigateur à une taille fixe avant chaque exécution et ne la modifiez plus. Temposhot capture la fenêtre à sa taille actuelle ; il ne redimensionne pas les fenêtres. Une note dans la politique, par exemple « fenêtre du navigateur de 1440 points de large, zoom à 100 % », maintient les captures de jours différents à la même échelle.

Nommer et stocker les images pour leur remplacement

Chaque image sera remplacée un jour. Nommez les fichiers pour retrouver rapidement toutes les images d'un même écran.

Un motif tel que area-task-step.png, par exemple billing-change-plan-03.png, trie les fichiers par domaine puis par tâche. Conservez un dossier par guide et stockez le Document Temposhot de chaque guide pour pouvoir réexporter après des modifications.

Les exports d'images de Temposhot utilisent les titres de page dans les noms de fichiers. Définissez les titres avant l'export, ou renommez les fichiers dans votre dépôt de documentation ensuite. Le package ZIP ajoute document.json aux pages PNG générées, ce qui est utile si vous scriptez l'import dans un système de documentation.

Structure de dossiers pour l'ensemble de l'exemple

Un dossier par domaine contient un dossier par guide. Les images exportées se trouvent à côté de la page qui les utilise, de sorte qu'une pull request modifiant un guide montre aussi les images modifiées.

Garder les titres de page et les noms de fichiers synchronisés

Comme Temposhot nomme les fichiers d'image d'après les titres de page, un titre tel que Click "Change plan" produit un nom de fichier difficile à trier. Deux approches fonctionnent : réécrire les titres de page dans leur forme finale destinée au lecteur et renommer les fichiers du dépôt avec un script, ou exporter un package ZIP et utiliser l'ordre des pages dans document.json pour nommer les fichiers.

Quelle que soit l'approche retenue, le numéro d'étape dans le nom de fichier doit correspondre au numéro d'étape de la page. Lorsque l'étape 4 est supprimée, renumérotez les fichiers suivants dans le même commit.

Stocker les Documents sources

Chaque image exportée provient d'un Document du Mac qui l'a enregistrée. Les Documents se trouvent dans la bibliothèque Documents (Command+4) de ce Mac, et Temposhot ne les synchronise pas. Nommez chaque Document exactement comme le dossier de son guide, par exemple billing-change-plan, afin de retrouver la source de n'importe quelle image en recherchant dans la bibliothèque.

Créer les guides de tâche avant les visites d'ensemble

Les guides de tâche répondent aux questions les plus fréquentes et sont les plus faciles à vérifier. Rédigez-les en premier.

1. Ouvrir Action Capture

   Appuyez sur Command+3, sélectionnez Start Action Capture et choisissez Specific Window.

2. Effectuer la tâche

   Parcourez la tâche une fois. Chaque clic accepté enregistre la fenêtre juste avant le clic, avec un titre provisoire issu de Parse clicked elements.

3. Terminer et modifier

   Sélectionnez Finish capture. Dans l'éditeur, réécrivez les titres, cadrez les pages et ajoutez les repères.

4. Exporter les pages

   Ouvrez More export formats et choisissez les pages PNG ou WebP pour le site de documentation.

Les visites du produit et les pages de vue d'ensemble viennent ensuite, une fois que les guides de tâche ont montré les écrans les plus importants. Le guide Action Capture et le guide d'export des Documents détaillent ces étapes.

Ordonner le premier lot par volume de tickets

L'équipe de l'exemple a capturé les neuf questions les plus posées pendant la première semaine. Chaque guide a pris environ 25 minutes : 5 minutes pour réinitialiser le compte de test, 5 minutes pour enregistrer, et 15 minutes pour modifier les titres, le cadrage et les repères. Les neuf guides ont demandé environ quatre heures au total.

Réécrire les titres provisoires en instructions

Parse clicked elements remplit chaque titre de page à partir du nom du contrôle, par exemple Click "Change plan". Les clics sur des contrôles sans nom lisible reçoivent Click here. Ces deux formes sont provisoires. Un titre destiné au lecteur commence par un verbe, nomme le contrôle en gras et ajoute le résultat lorsqu'il n'est pas évident.

Titre provisoire	Titre réécrit
Click "Billing"	Ouvrir Billing dans la barre latérale
Click here	Sélectionner la carte du forfait Team
Click "Confirm"	Sélectionner Confirm pour changer de forfait au prochain renouvellement

Le titre réécrit devient aussi le nom du fichier image à l'export. Un titre clair sert donc à la fois au lecteur et au dépôt.

Vérifier le nombre d'étapes par rapport à la limite gratuite

Le forfait gratuit met en pause une exécution d'Action Capture après 5 étapes, et les étapes déjà capturées restent enregistrées. Les guides de sept étapes comme ceux de l'exemple nécessitent Temposhot Pro, ou deux exécutions ajoutées à un même Document. Pour ajouter une seconde exécution, utilisez Capture new images… dans le panneau Pages : les nouvelles images sont ajoutées au Document ouvert.

Modifier les pages avec les raccourcis clavier

La modification représente la plus grande partie des 25 minutes par guide. Les touches de l'éditeur ci-dessous couvrent les modifications les plus courantes sur les pages de documentation.

Les annotations ne sont pas destructives. Un rectangle ajouté dans cette version peut être déplacé ou supprimé après la prochaine refonte sans recapturer l'étape, tant que l'écran sous-jacent correspond toujours.

Relier l'ensemble de documentation

Les lecteurs arrivent rarement directement sur la page dont ils ont besoin. Reliez les pages pour qu'ils passent d'un concept à la tâche, ou d'une erreur à sa correction.

• Chaque guide de tâche renvoie à ses prérequis et à la tâche suivante probable.
• Chaque page de dépannage renvoie au guide de tâche qui corrige le problème.
• Chaque page de référence renvoie aux tâches qui utilisent l'écran.

Une courte page d'index par domaine, qui liste les tâches par objectif, aide les lecteurs qui parcourent plutôt que de chercher.

Schéma de liens à partir d'une question

La question « Pourquoi mon export est-il vide ? » de l'exemple a produit une chaîne de quatre pages. Un lecteur qui arrive sur l'une d'elles peut atteindre les trois autres en un clic.

Éviter les pages orphelines

Après la publication, listez toutes les pages et comptez leurs liens entrants. Une page sans lien entrant n'est accessible que par la recherche. Dans l'exemple, 4 des 52 pages n'en avaient aucun. Chacune a été ajoutée à l'index de son domaine.

Attribuer les responsabilités et les déclencheurs de relecture

Attribuez un responsable à chaque page, généralement l'équipe propriétaire de la fonctionnalité. Indiquez la version du produit à laquelle correspondent les captures.

Les déclencheurs de relecture sont plus efficaces que les seuls rappels calendaires :

• Une version modifie un écran présent dans l'ensemble.
• Un libellé ou un élément de menu est renommé.
• Le support signale une étape qui ne correspond plus.
• Un intervalle fixe s'écoule, par exemple un trimestre, sans autre déclencheur.

L'article sur la mise à jour de la documentation à base de captures d'écran décrit la routine de mise à jour.

Remplacer les images après une version

Lorsqu'une version modifie un écran, les noms de fichiers permettent de retrouver facilement les images concernées. Recherchez dans le dépôt le préfixe du domaine, ouvrez les Documents correspondants et réexécutez uniquement les étapes modifiées.

Une nouvelle page issue d'une capture peut être insérée après la page sélectionnée. Sélectionnez la page qui précède l'étape modifiée, lancez la capture, et la nouvelle page se place à la bonne position.

Répartir les responsabilités par domaine

Un seul rédacteur ne peut pas relire 52 pages après chaque version. L'équipe de l'exemple a confié chaque domaine à l'ingénieur qui en est responsable, le rédacteur assurant la relecture. Le responsable signale les écrans modifiés dans le ticket de version, et le rédacteur remplace les images.

Indiquer la version du produit sur chaque page

Ajoutez la version du produit dans les métadonnées de la page ou sur sa dernière ligne, par exemple « Captures conformes à la version 4.2 ». Lorsque le support signale un écart, la version indique de combien de versions la page est en retard. Les pages en retard de plus de deux versions passent en tête de la file de relecture.

Questions fréquentes

Combien de captures d'écran une page de documentation doit-elle contenir ?

Une par étape dans les guides de tâche, et le moins possible ailleurs. Chaque image représente une mise à jour future : n'en ajoutez une que lorsqu'elle évite un effort au lecteur.

Les captures de documentation doivent-elles montrer l'écran entier ?

Rarement. Recadrez sur la fenêtre ou le panneau. Les captures plein écran montrent des applications sans rapport et réduisent la taille du texte de l'interface.

Qu'est-ce que la documentation visuelle ?

Une documentation qui associe au texte des captures d'écran, des schémas ou des vidéos. Voir documentation visuelle dans le glossaire.

Quel format d'image un site de documentation doit-il utiliser ?

Les pages PNG gardent le texte de l'interface net. Les pages WebP donnent des fichiers plus légers et n'apparaissent dans More export formats que si un encodeur WebP est disponible sur le Mac. Image Compressor peut réduire davantage les fichiers PNG avant l'envoi.

Combien de temps prend la mise à jour des captures après une refonte ?

Cela dépend du nombre d'images qui montrent les écrans modifiés. Dans l'exemple, la refonte d'un domaine touchait environ 50 des 247 images. Réexécuter uniquement les étapes modifiées à partir des Documents enregistrés a pris un à deux jours, contre environ une semaine pour reconstruire les mêmes guides depuis le début.

Plusieurs rédacteurs peuvent-ils partager un même Document Temposhot ?

Non. Les Documents sont stockés sur le Mac qui les a créés. Partagez les fichiers exportés via le dépôt de documentation, et conservez le Document source de chaque guide sur le Mac de son responsable.

Transformez vos clics en guide pas à pas clair

Action Capture enregistre chaque guide de tâche en une seule passe, avec une taille de fenêtre constante et des titres provisoires. Téléchargez Temposhot et commencez par la question la plus fréquente de votre liste.