Attention à l'abus de balises "question"/"information". Je me permets de recopier ici un conseil que j'ai envoyé par MP y'a pas longtemps :
Si ça peut paraître une bonne idée au départ, le fait d'articuler la quasi-totalité du tutoriel dans un question-réponse le rend difficile à suivre : tu attires beaucoup plus l'attention du lecteur sur les questions qu'il est censé poser que sur ton code et les explications qui l'accompagnent. Je te suggère d'adopter une forme plus sobre, plus directe : avoir une balise question/information de temps en temps permet de soulever un point-clé à retenir. S'il yen a une toutes les 3 lignes, elles ne mettent plus rien en valeur.
Il s'agit de se servir du rythme de ton tutoriel pour taquiner le cerveau du lecteur. Par exemple, tu veux qu'une section mette en valeur et résolve un problème technique qui se pose dans la partie précédente : commence par un paragraphe plat qui explique le problème, peut-être en t'appuyant sur du code (au passage, ne masque pas le code, à moins que ce soit la solution d'un exercice). Puis dès que le problème est posé/isolé, casse le rythme et pose ta question :
Comment faire pour… (résoudre ce truc) ?
À ce moment-là, en cassant le rythme brutalement avec ta question, tu viens de réveiller le lecteur et d'attirer toute son attention sur ce qui va suivre : tu peux commencer à resoudre le problème posé avec des explications préliminaires, un code qui fait le job, des explications détaillées sur ton code pour ne pas perdre les débutants, peut-être avec des liens vers la doc standard pour éviter de la paraphraser. Et maintenant, tu veux qu'il ressorte de ta section en ayant retenu "le truc", l'idée-clé qui a débloqué la situation…
Essaye d'adopter ce genre de rythme, tu verras que même en te relisant tu trouveras tes propres explications plus nettes, plus aérées, plus agréables à suivre.