📋 [A LIRE] Créer un tutoriel : Les bonnes pratiques

tutoriel

#1

Créer un tutoriel


Bonjour a tous !

Nombreux d’entre vous souhaitent créer des tutoriels sur le forum afin d’aider la communauté qui entoure Gladys, et nous leurs en sommes plus que reconnaissant. :raised_hands:
Ce topic a donc pour but de vous énoncer les bonnes pratiques pour rédiger un tutoriel clair et efficace !

Commençons par le début


Avant toutes choses commencez par un “Bonjour” “Salut” “Hello tout le monde” enfin bref, une forme de politesse quelconque (ça n’a jamais tué personne :laughing:).

Ensuite faites une petite introduction, décrivez l’objectif de votre tutoriel, ses avantages/inconvénients par rapport à un autre tutoriel/une autre solution déjà présent(e) ou non sur le forum.

Et ensuite ?


Rédigez les prérequis !

Si vous vous lancez dans un tutoriel sans prérequis vous risquez de perdre l’utilisateur (ou de vous perdre) dés le début et il passera son chemin ou alors fera des erreurs et se découragera… ce que l’on ne souhaite pas bien évidemment.

Il est important de situer le contexte pour savoir d’où l’on part et où l’on va.

Bon alors exécutez Appollo dans Gladys pour lancer Saturne et puis tapez la commande truc-muche pour installer le module machin.

Je vous ai perdu n’est-ce pas ?
Hors si j’avais fait =>

Prérequis

Le module machin nécessite d’installer la librairie Saturne, qui est là pour faire la liaison entre le module Gladys et votre capteur truc. La librairie Saturne nécessite l’installation de Appollo qui est un plugin pour Raspberry Pi et qui fait tourner quelque chose.
Il faut donc installer Appollo avant toutes choses dans Gladys:
pour ça tapez la commande…
puis…

Vous aurez compris de quoi je vous parlais.

Vous allez me dire “ouai mais ce que tu as écris ça n’a pas de sens !”, oui c’est vrai mais ça illustre bien l’importance du prérequis !

RĂ©digez votre tutoriel


Une fois que vous avez terminé ces étapes vous pouvez enfin commencer à rédiger votre tutoriel !

Pour que votre tutoriel soit le plus lisible possible utilisez tous les moyens qui sont Ă  votre disposition.
Le forum intègre le Markdown utilisez-le !

Pour ceux qui ne connaissent pas => Le Markdown

Essayez de mettre en forme votre tutoriel le mieux possible

  • Faites des paragraphes et espacez-les
  • CrĂ©ez des titres de diffĂ©rentes tailles pour attirer l’attention de l’utilisateur

Regarde

Regarde

Regarde

Regarde

Il est important de ne pas noyer l’utilisateur dans d’énorme pavés de texte.

  • Balisez les Ă©ventuelles lignes de code (vous pouvez le faire de deux façons diffĂ©rentes ! )

Salut c’est moi la ligne de code balisée ! On m’utilise généralement pour de grosse commandes, ou d’important morceau de texte car je prend systématiquement toute la ligne quelque soit la taille de ma commande

Salut c'est encore moi ! On m'utilise généralement pour de petites commandes insérées dans des explications car je suis délimitée

  • Utilisez le Gras pour noter l’importance d’une Ă©tape de votre tutoriel.
  • A l’inverse utilisez l’italique pour une info utile mais pas indispensable (ou une petite blague :wink: )
  • InsĂ©rez des photos/captures d’écrans pour Ă©claircir vos instructions
  • Un excellent module aussi pour mettre en avant certaines Ă©tapes critiques https://asciinema.org/

Évitez les captures d’écrans de tout votre écran avec un montage digne d’un enfant de 5 ans ! :joy:

Il existe tout un tas de petit logiciel gratuit pour éditer une image comme Paint.net très facile a prendre en main.

Vous pouvez également vous servir d’outil du type GreenShot pour capturer des zones d’écran et les éditer/partager/héberger, etc…

Préférez une plus petite capture mais avec un montage plus esthétique.


Vous pouvez aussi créer des listes numérotés pour indiquer l'ordre des étapes avec des sous-puces pour indiquer les sous-étapes
  1. Étape 1.1
  2. Étape 1.2
    • Étape 1.2.1
    • Étape 1.2.1.2
  3. Et ainsi de suite…

Utilisez une liste déroulante si votre tutoriel présente plusieurs configurations différentes

Configuration 1

Installer saturne

Configuration 2

Installer apollo

Configuration 3

Bon ça suffit tu vas pas ouvrir toutes les listes du forum non plus ! :joy:

Et tout ce petit monde est disponible ici quand vous Ă©crivez votre tutoriel (ou un message quelconque) sur le forum


Je vous ai encadré en vert l’icone (numéroté 1) sur lequel il faut cliquer pour accéder au menu popup et ainsi pouvoir utiliser les liste déroulantes (numéroté 2).

Vous voyez comme c’est simple de comprendre avec une belle capture d’écran qui illustre les étapes à suivre ! :wink:

Tutoriel terminé ?


Écrivez une petite phrase pour clôturer votre tutoriel ou, si possible, faite carrément un exemple d’utilisation afin d’aider l’utilisateur à démarrer !

Points importants !


  • Relisez vous ! Plusieurs fois !
  • Prenez votre temps !
  • Faites attention Ă  votre orthographe !
  • Mettez vous Ă  la place de l’utilisateur quand vous rĂ©digez (tout le monde n’a pas votre niveau de connaissance) !
  • Utilisez votre tutoriel chez vous pour voir si vous n’avez rien oubliĂ© ou si quelque chose n’est peut ĂŞtre pas assez clair !
  • Vous pouvez utiliser des Ă©diteurs externes au forum pour mieux visualiser votre tutoriel avant de le publier (j’ai utilisĂ© Stackedit qui est un Ă©diteur en ligne, pour rĂ©diger ce post)
  • NĂ©cessitez pas Ă  nous envoyer votre tutoriel Ă  @C4rlit0 et moi mĂŞme (@LepetitGeek) avant de le publier pour vous aidez Ă  le mettre en forme ou Ă  le corriger :wink: !

Voila je pense avoir fait le tour des bonnes pratiques nécessaire pour rédiger un tutoriel sur le forum (et partout ailleurs)

Sur ce, bon tuto ! :grin:

Spoil

Je vous ai eu ! https://media.giphy.com/media/PjtuaVinQN7cA/giphy.gif


[TUTORIEL] sur le montage et paramétrage de capteur/actionneur
[TUTORIEL] Préservation de la carte SD
closed #2

pinned #3