Salut à tous,
Voici comment je procède pour écrire des articles techniques, afin de les rendre lisibles, et utiles pour le futur moi qui veut se souvenir comment utiliser cette techno dont j'ai écrit un article il y a plusieurs mois.
Tu viens juste de lire l'introduction. Je commence par une introduction, car mon thème prend ce texte comme résumé dans la première page.
Voici le début de mon fichier taxonomies.md:
*archetype de posts*
--
Aujourd'hui, en français, je souhaite aborder le sujet des archétypes du moteur de génération de site Hugo. Ce moteur très performant est d'ailleurs utilisé pour générer ces pages.
<!--truncate-->
Certains thèmes comprennent la "balise more", donc elle termine mon intro.
Je peux terminer mon intro après le <!-- more --> si je pense qu'elle doit être complétée.
Titres
Je continue le post en utilisant les titres. Je pense que les titres sont importants, car ils nous permettent de comprendre la structure de l'article, et permettent aux "utilisateurs expérimentés" d'aller directement à la section qui les intéresse.
Sur mon précédent article, sur les archétypes, mes titres étaient:
# archetypes/Default.md
(...)
# archetypes/mon_mien.md
(...)
J'aurais pu utiliser une structure plus complexe en utilisant le deuxième ou le troisième niveau de titres
# First level
## Second level
### Third level
Ce code apparaitra ainsi sur le blog :
First level
blablabla
Second level
blablabla expliqué
Third level
blablabla détail
C'est important d'utiliser les titres sur vos tutos. Parfois, les lecteurs lisent plus d'un article en même temps, et il est plus facile pour eux de passer à la partie suivante lorsque les titres organisent la page.
Bout d'code
Il existe deux types de méthodes pour mettre du code en markdown:
code dans un ligne de texte
C'est quand tu utilises la balise "code" ``` 'my code is cool' ``` dans la même ligne que le texte que tu écris.
Isolement des lignes de codes
Il s'agit de présenter son code ainsi :
```
my code is cool
```
Le code est alors isolé dans son propre paragraphe.
Mon avis sur la question
Utilisez toujours le second. Pour une raison simple: les gens utilisent le copier/coller. Et il est tellement plus facile de copier coller un code sur une ligne isolée.
Astuces en vrac
Bullet points
- Ne pas
- les utiliser
- n'importe
- comment
Ne les utilisez que lorsque c'est pertinent, c'est à dire dans deux cas :
- Pour une lite de trucs
- Pour une liste de machins
Utiliser la balise "citation" pour les citations
Utiliser les citations pour les citations. Je sais que ça sonne un peu stupide, mais tu pourrais vouloir utiliser le format "citation" pour autre chose parce qu'il est joli. Ne le fais pas.
Quote style is for quote - Dr. CssProvider