User Documentation Dans ce tutoriel, vous allez apprendre comment créer un tutoriel.
Un tutoriel est une leçon qui vous guide à travers une série d'étapes pratiques. Il offre une expérience d'apprentissage en faisant quelque chose. C'est la meilleure façon de se familiariser avec un sujet que l'on ne connaît pas encore. Les tutoriels sont essentiels dans toute documentation : ils font visiter les lieux aux nouveaux arrivants, ils guident les premiers pas, ils constituent la vitrine, ils donnent une expérience agréable et facile d'un sujet. L'une des "astuces" pour y parvenir est de laisser de côté tout ce qui peut distraire dans le processus d'apprentissage. Par exemple :
- Les façons alternatives de faire quelque chose ou les façons de faire quelque chose de très spécifique.
- Les références complètes de tous les paramètres et une description technique de leur structure.
- Les explications détaillées et les contextes historiques.
Ces informations supplémentaires sont mieux fournies séparément. Évitez autant que possible de les mélanger, car cela ne ferait qu'embrouiller le tutoriel. C'est le principe fondamental du cadre Diátaxis, une méthode systématique pour améliorer la documentation. Placez les informations supplémentaires mentionnées ci-dessus dans des guides pratiques, des références et des explications respectifs. Dans les guides pratiques, vous pouvez trouver rapidement comment accomplir quelque chose de spécifique. Dans les références, vous pouvez consulter comment les choses fonctionnent, quels paramètres elles ont et où trouver plus d'informations. Avec les explications, vous pouvez approfondir votre compréhension du sujet.
Bien qu'un tutoriel offre une introduction à un sujet, il n'est pas exclusivement destiné aux débutants. Il peut également constituer une introduction à un sujet avancé ! Soyez clair dès le début de votre tutoriel sur les connaissances ou les compétences nécessaires pour pouvoir le réaliser.
Si vous apprenez à quelqu'un à cuisiner, vous devez expliquer des choses comme les techniques de découpe, comment utiliser un four et d'autres notions de base en cuisine. Vous commencez par une recette simple, de préférence quelque chose qui donne facilement un beau résultat final. Ce résultat final n'est pas le but principal en soi : vous voulez enseigner certaines compétences. C'est ce que fait un tutoriel. Quelqu'un qui sait cuisiner et qui veut faire quelque chose de spécifique n'a pas besoin d'un tel tutoriel, mais d'une recette. Les recettes sont les guides pratiques de la cuisine.
Étape par étape
Pour créer un tutoriel :
- Rassembler des informations sur le sujet. Documentation existante, vidéos, etc. Noter les points qui prêtent à confusion ou qui ont demandé du temps à comprendre. Y a-t-il des questions sur le sujet dans le forum ?
- Quels concepts sont impliqués ? Esquisser un petit schéma peut aider. Ne pas chercher à être exhaustif, mais indiquer clairement ce qui est important pour ce tutoriel et ce qui ne l'est pas.
- Y a-t-il une connaissance ou une compétence spécifique à enseigner dans votre tutoriel ?
- Créer un exemple dans lequel vous pouvez utiliser tous les concepts et compétences que vous souhaitez transmettre dans le tutoriel. Rendre l'exemple aussi simple que possible.
- Définir et rédiger les étapes permettant d'arriver à un résultat final. Chaque étape doit pouvoir être reproduite par votre élève.
- Filtrer toutes les explications, références, alternatives et cas particuliers ; les placer dans des articles séparés.
- Rédiger une introduction. Que va-t-on apprendre dans ce tutoriel ? Mentionner les prérequis nécessaires pour suivre le tutoriel.
- Rédiger la conclusion. Qu'avons-nous appris ? Vous pouvez aussi mentionner les étapes suivantes pour en apprendre davantage.
- Ajouter des captures d'écran annotées pour illustrer les actions à effectuer. Astuce : utiliser des numéros dans la capture d'écran et donner les explications dans le texte. Cela facilite la réutilisation de votre capture d'écran dans les traductions et minimise l'effort de production de captures d'écran spécifiques à chaque langue.
- Ajouter des schémas pour expliquer les structures, relations et processus.
- Ajouter les articles associés avec explications, références et guides pratiques.
- Regrouper tous les articles d'un sujet sous un article de synthèse, expliquant ce qui est quoi, comment ils sont liés et par où commencer.
Exemple : Créer et publier un article dans Joomla
À titre d'exemple, créons un tutoriel sur la manière de créer et publier un article sous un lien de menu dans Joomla.
Rassemblement d'informations
Dans notre manuel utilisateur, vous trouverez des articles pertinents sous « Démarrage », « Articles » et « Menus ». Il est souvent déroutant, au début avec Joomla, de ne pas voir un article après l'avoir créé, même si vous l'avez marqué comme « publié ». Pour voir l'article, il faut qu'un lien y mène. Il existe plusieurs façons de créer un tel lien (comme un lien de menu, une disposition de blog de catégorie, ou en le plaçant sur la page d'accueil en mode blog en marquant l'article comme épinglé, ou encore en créant un lien depuis un autre article), mais nous allons maintenant nous concentrer sur la mise à disposition de l'article via un lien de menu.
Concepts & Compétences
Nous avons « contenu », « article », « menu » et « lien de menu ». Il faut clarifier ces termes. Nous montrons où trouver ces éléments dans le menu d'administration. Nous laissons de côté « catégories » ou « épinglé » dans ce tutoriel.
Prérequis
Vous devez avoir accès à l'administration d'un site Joomla fonctionnel et savoir vous connecter.
Objectif
Notre objectif est d'apprendre à créer un nouvel article Joomla et un nouveau lien de menu sous lequel nous placerons notre article.
Étapes
Suivez les étapes suivantes pour atteindre notre objectif :
A. Créer un article
- Connectez-vous à l'administration de votre site Joomla.
- Nous allons d'abord créer l'article. Accédez au menu « Contenu » sur la gauche et sélectionnez « Articles ».
- Cliquez sur « Nouveau » pour créer un nouvel article.
- Saisissez un titre et un contenu pour votre article.
- Cliquez sur « Enregistrer & fermer » pour enregistrer votre article.
B. Créer un lien de menu renvoyant vers l'article
Afin d'afficher l'article sur le site, nous allons créer un lien de menu renvoyant vers l'article. Accédez au menu « Menus » sur la gauche et sélectionnez « Menu Principal ».
- Comme pour un article, cliquez sur « Nouveau » pour créer un nouveau lien de menu.
- Saisissez un titre pour votre lien de menu. C'est le titre tel qu'il apparaîtra dans le menu. Il n'est pas obligatoire qu'il soit identique au titre de l'article. Il est généralement plus court que le titre d'un article afin de mieux s'intégrer dans le menu.
- Sélectionnez un type de lien de menu : sous « Articles », sélectionnez « Article simple ».
- Sélectionnez l'article : sélectionnez l'article que nous venons de créer.
- Allez sur le site et actualisez la page. Félicitations : vous pouvez maintenant cliquer sur le lien de menu pour voir votre article.
Introduction
Rédigez l'introduction : ce que vous allez apprendre dans ce tutoriel et les prérequis nécessaires.
Filtrer les informations supplémentaires
Pouvons-nous omettre quelque chose de ce qui a été écrit jusqu'à présent ? Eh bien, à l'étape 2 de la création d'un lien de menu, j'ai mentionné que le titre du lien de menu n'a pas besoin d'être identique au titre de l'article. Est-ce un ajout nécessaire à ce tutoriel ? Si ce n'est pas le cas, mieux vaut l'omettre pour l'instant. Mais cela donne une piste pour un article plus spécialisé sur les titres d'articles et les titres de menus et sur le moment où ils sont affichés, impliquant les paramètres généraux des articles, les paramètres individuels de l'article sous l'onglet paramètres, les paramètres du lien de menu sous l'onglet paramètres du lien de menu, et plus encore. Il serait également utile de rédiger un article de type référence sur la façon dont les articles, les catégories et les liens de menu fonctionnent ensemble ; dans un tel article, essayez d'être complet, en listant toutes les possibilités. Un guide pratique spécialisé pourrait être : « Comment afficher le titre de l'article ? », montrant les paramètres dans les réglages généraux des articles, ainsi que dans les paramètres individuels de l'article et du lien de menu. Un article de type explications pourrait expliquer le contexte expliquant pourquoi Joomla utilise « article » là où, par exemple, WordPress utilise « post », ou comment l'article est rendu dans la page finale.
Conclusion
Résumez l'ensemble dans une synthèse. Mentionnez également quelques étapes suivantes possibles pour en apprendre davantage (comme un tutoriel sur l'ajout d'une catégorie ou un guide pratique sur le raccourci d'enregistrement vers le menu).
Images et graphiques
Réalisez des captures d'écran montrant les boutons et champs concernés par la création d'un article et d'un lien de menu. Marquez les boutons et champs concernés.
Pour plus de clarté, vous pourriez ajouter un diagramme montrant comment un article est placé « sous » un lien de menu.
Ajouter des références, des guides pratiques et des explications
Placez toutes les informations et instructions supplémentaires dans des articles séparés.
Aperçu
Si vous avez plusieurs articles sur un même sujet, vous devriez créer un article de synthèse, expliquant comment les articles sont liés entre eux et par où commencer.
Exercice
Commencez à rédiger le tutoriel ci-dessus sur la façon de créer et de publier un article dans Joomla. La meilleure façon d'apprendre, c'est en pratiquant. Nous publierons un exemple de ce à quoi cela peut ressembler dans le manuel utilisateur actuel de ce site. Mais nous serions ravis d'y intégrer votre version si vous parvenez à améliorer la version actuelle.
(cet article a également été publié dans le Joomla Community Magazine de février 2025)