Commencer par un exemple lisible
Un bloc de code peut être présenté sous forme de texte avec une mise en page simple. La coloration syntaxique et l’éditeur interactif sont des enrichissements, pas des conditions pour comprendre une commande courte. Évitez de charger un environnement de démonstration complet sur chaque page lorsqu’un extrait accompagné d’une explication répond déjà au besoin.
Soigner la largeur et la copie
Les lignes longues doivent rester consultables sans faire déborder toute la page. Un bouton de copie doit annoncer son résultat et conserver le contenu exact, sans numéros de ligne ajoutés par la présentation. Testez les exemples contenant des accents, des guillemets et plusieurs lignes : une copie visuellement réussie peut encore produire un texte inutilisable.
Séparer la démonstration du guide
Si une simulation est utile, proposez son lancement avec un contexte clair. Le lecteur doit pouvoir consulter la documentation même si cette démonstration échoue. Conservez un sommaire et des liens stables vers les sections, puis vérifiez leur comportement avec les en-têtes fixes. La navigation entre référence, exemple et explication doit rester directe sur un petit écran.