Pages HTML explainer
L'utilisateur lit ces pages dans un navigateur et Cmd+clique depuis elles directement dans VS Code. Il comprend un flux depuis une swimlane beaucoup plus rapidement qu'à partir de paragraphes, et il veut que chaque page réponde à ce qu'il a demandé et rien de plus.
Fichiers de cette compétence
assets/template.html: le point de départ de chaque page. Copiez-le, ne créez jamais une page à partir de zéro.references/DESIGN.md: le design que chaque page suit, toujours dans sa forme sombre, avec chaque lien une pilule bleue (references/page.md, « L'apparence »). Lisez-le quand une page nécessite une couleur ou un élément que le modèle ne possède pas.references/page.md: nom du fichier et emplacement, la barre latérale, les liens vers les fichiers, la section des tâches, la section Pages liées, les pages maîtres et explainer. Lisez-le lors de la création d'une page ou de la modification de sa structure.references/writing.md: la section problème et tout texte en prose. Lisez-le avant d'écrire du texte.references/diagrams.md: à quoi ressemble une swimlane et comment la vérifier. Lisez-le avant de dessiner ou de modifier un diagramme.references/playable.md,assets/player.js,assets/player.css: swimlanes jouables. Lisez-les quand l'utilisateur dit « jouable », ou lors de la modification d'une page qui contient undiv.player.
L'apparence
Chaque page suit references/DESIGN.md, toujours en sombre, avec chaque lien une pilule bleue pour qu'il se
démarque comme cliquable : souligné pour un fichier, ↗ pour une autre page, ni l'un ni l'autre pour une section de la même page
(references/page.md, « L'apparence : DESIGN.md, toujours sombre » et « Trois types de liens »). Le modèle fait déjà
cela. Chaque diagramme se trouve dans un panneau que le lecteur peut redimensionner, zoomer et faire glisser (references/diagrams.md,
« Le bloc diagramme »).
Gardez la page minimale
Une page ne contient que ce que l'utilisateur a demandé. Toute section, tableau ou note supplémentaire est quelque chose qu'il doit parcourir pour trouver la réponse.
- Sections : uniquement celles dont la demande a besoin. Une swimlane avec un court paragraphe autour constitue une section. N'ajoutez jamais une section que l'utilisateur n'a pas demandée : pas de résumés, pas d'inventaires, pas de section « raisons », pas de registre des décisions passées.
- Tableaux : seulement lorsque l'utilisateur en demande un. Écrivez plutôt des paragraphes et des swimlanes.
- Sous un diagramme : rien. Pas de liste de fichiers, pas de notes, pas de ligne « non dessiné ». Si une phrase est nécessaire pour lire le diagramme, elle se trouve dans le paragraphe qui le précède.
Quelles sections une demande reçoit
Adaptez la page à la question :
-
« Quel est le problème », débogage, correction d'un bug : d'abord la section problème (
references/writing.md), contenant une swimlane du bug (sur une page maître, une page jouable,references/playable.md). Ensuite, toutes les swimlanes supplémentaires nécessaires à l'explication. -
Implémentation d'une fonctionnalité ou correction d'un bug, une fois les tâches discutées : une section tâche juste en dessous de la section problème (
references/page.md, « La section tâche »). Tant que l'utilisateur est encore en train de cerner le problème, il n'y a pas encore de tâches, donc il n'y a pas de section tâche. -
« Comment cela fonctionne-t-il », « De quoi parle ce projet » : pas de section problème, pas de section tâche. Une swimlane du flux, avec de courts paragraphes là où ils aident.
-
« Comment construire quelque chose comme ça » : une seule section : la swimlane habituelle pour cela, les fonctionnalités supplémentaires qui pourraient être ajoutées et comment procéder.
-
Toute page liée à d'autres pages (une page maître et ses explainers, ou des pages que l'utilisateur demande de lier) : une section Pages liées tout en bas (
references/page.md, « La section Pages liées »).
Tout le reste : répondez à la question avec le moins de sections qui y répondent.
Diagrammes : uniquement des swimlanes
Il existe deux types de diagrammes, et seulement deux :
- Swimlane : un organigramme avec une boîte par acteur ou système, des étapes à l'intérieur de la boîte qui les exécute,
des flèches traversant les boîtes lorsque le travail se déplace (
references/diagrams.md). - Swimlane jouable : la même swimlane avec des boutons Réinitialiser / Précédent / Suivant / Lire, une flèche par pression,
et une légende en dessous (
references/playable.md). « Jouable », « swimlane jouable », « diagramme jouable » et « avant/après jouable » signifient tous cela. « Swimlane » seul signifie une swimlane simple.
Toute autre demande de diagramme (« un diagramme Mermaid », « dessinez le flux », « un diagramme de cela ») reçoit une swimlane.
Workflow
- S'agit-il d'un explainer d'une page maître ? Greppez le dossier du ticket pour une phrase distinctive
de la demande, même lorsque l'utilisateur ne colle que le texte d'un élément et ne nomme jamais la page maître.
Si cela correspond, la nouvelle page est l'explainer de cette page maître : utilisez le préfixe du nom de fichier de la page maître et liez
dans les deux sens dans la même modification (
references/page.md). - Créez le fichier (
references/page.md, « Le fichier »), copié à partir deassets/template.html. Remplissez les espaces réservés{{…}}, et changez la clélocalStoragetoc-open-CHANGE-MEen une clé unique pour la page. - Décidez des sections à partir de « Quelles sections une demande reçoit », et écrivez uniquement celles-ci.
- Dessinez les swimlanes (
references/diagrams.md). Avant de rendre, listez chaque boucle, branche, chemin d'échec et retour anticipé dans le code couvert, et vérifiez que chacun est dessiné. - Lie chaque référence de fichier avec
#L<ligne>. Vérifiez que chaque chemin existe et que chaque ligne cible dit réellement ce que le texte prétend. - Exécutez les vérifications ci-dessous, puis rapportez dans le chat avec le lien de la page (ci-dessous). Si quoi que ce soit que le code fait est omis d'un diagramme, dites-le dans cette réponse.
Vérifications avant de dire que c'est terminé
- La page n'a que les sections nécessaires à la demande : pas de section problème sauf si elle explique un problème, pas de section tâche sauf si des tâches ont été discutées, pas de tableau sauf s'il a été demandé, rien sous un diagramme.
- Lorsque la page explique ce qu'une personne a dit ou veut, sa première phrase dit ce qu'elle veut, en
propres termes que l'utilisateur utiliserait (
references/writing.md, « Expliquer ce que quelqu'un voulait dire »). - La page conserve l'apparence du modèle : toujours sombre, chaque couleur provenant de
references/DESIGN.md, chaque lien une pilule bleue avec sa marque unique, aucun thème clairprefers-color-schemeajouté (references/page.md, « L'apparence »). - Les légendes nomment les significations, pas les couleurs (« là où ça tourne mal », jamais « ocre = … ») ; la page n'a pas de liste
de ses propres couleurs (
references/page.md). - Chaque diagramme est une swimlane : la page n'a pas de
sequenceDiagram,stateDiagram,classDiagramou autre type de diagramme. - Rendu de chaque diagramme avec mermaid-cli et vérification du PNG (
references/diagrams.md, « Rendre pour vérifier »). La page doit se charger sans erreurs de syntaxe Mermaid. - Chaque boîte qui envoie, écrit, appelle ou lit indique à ou depuis où dans son texte, et sa flèche se termine sur la boîte de ce système. Chaque appel à un autre système est une flèche sortante, plus une flèche de retour lorsque l'étape suivante utilise la réponse.
- Voies de swimlane : greppez la source pour
[" "]etghost; il ne doit y en avoir aucun. Dans le PNG, aucune boîte de voie n'est plus large ou plus haute que le nécessaire pour ses propres étapes. - Une swimlane jouable : parcourez-la du début à la fin et en arrière dans un navigateur.
- Chaque
hrefetdata-hrefde la barre latérale correspond à unidsur la page, et chaque chemin de lien de fichier existe par rapport à la page. - Une page explainer : la page maître y fait référence partout où elle aborde le sujet, et le lead de l'explainer renvoie à la page maître.
- Pages liées : chaque page liste l'autre dans sa section Pages liées, la section est la dernière de la page, et chaque lien qu'elle contient ouvre un fichier existant.
- Après avoir changé le statut d'une tâche : un grep liste la classe de case à cocher et le libellé de chaque tâche côte à côte, et toutes
les tâches terminées se ressemblent (
references/page.md). - Un onglet de navigateur ouvert par automatisation est généralement en arrière-plan (
document.visibilityState === "hidden"), donc les événements de défilement ne se déclenchent pas là. Testez le scroll-spy en appelantmarkActive()après chaquescrollIntoView(), et ne concluez pas qu'il est cassé.
Mentionner une page dans le chat
Chaque fois qu'une réponse de chat mentionne une page HTML, donnez deux lignes que l'utilisateur peut coller directement dans la barre d'adresse du navigateur, chacune seule sur sa propre ligne :
file:///Users//<dépôt>/_/.html
/Users//<dépôt>/_/.html
La première ligne est l'URL complète file:///, la seconde est le chemin absolu sur le disque. Rien d'autre ne va sur
l'une ou l'autre ligne : pas de prose, pas d'accents graves, pas de lien markdown, pas de puce, pas de > blockquote. Mettez une courte étiquette sur
la ligne ci-dessus si nécessaire (« Collez ceci dans votre navigateur : »). Ajoutez un #id de section à l'URL lorsque vous
faites référence à une section, après avoir vérifié que l'id existe. Les fichiers de code dans le chat conservent les liens relatifs habituels.
Pourquoi : un lien relatif ouvre la source HTML dans VS Code, et un lien file:/// ouvre la page rendue
dans le navigateur. Une URL enfouie dans une phrase ou enveloppée dans du markdown doit être extraite à la main.