Guide des procédures

Ce guide est une adaptation du guide The Good Docs Project’s how-to. Utilisez ce guide pour enrichir chacune des sections du modèle de procédure.

Introduction

Une procédure amène vos utilisateurs à travers une série d’étapes nécessaires à la résolution d’un problème précis. Elle leur montre comment résoudre un problème concret ou accomplir une tâche en utilisant Koha, telle que comment fermer une bibliothèque.

Note

Une tâche est une action que vos utilisateurs peuvent réaliser avec Koha pour atteindre un objectif. Plusieurs tâches peuvent être nécessaires pour atteindre un objectif.

Une procédure décrit clairement une série d’étapes successives pour réaliser une tâche. La procédure suppose que l’utilisateur connaît les bases de Koha.

Les procédures sont souvent confondues avec les tutoriels. Les procédures sont dédiées à une tâche alors que les tutoriels sont axés sur l’apprentissage. Les différences entre les deux :

Tutoriel

Procédure

Axé sur l’apprentissage : aide les débutants ou les experts à apprendre une nouvelle fonctionnalité par une approche pratique.

Dédiée à une tâche : aide un expert à réaliser une tâche ou résoudre un problème.

Suit un chemin soigneusement préparé du début à la fin.

Vise un résultat positif et guide l’utilisateur à travers la voie la plus sécure vers l’objectif.

Evite tout scénario imprévu et garantit aux utilisateurs une réussite.

Avertit l’utilisateur de la possibilité de scénarios imprévus et lui indique comment les gérer.

Suppose que les utilisateurs n’ont aucune connaissance pratique et doit clairement présenter tous les outils, les configurations de fichiers, les détails de conception, etc.

Suppose que les utilisateurs ont des connaissances pratiques.

Pourquoi ai-je besoin d’une procédure ?

Une procédure est souvent utilisée pour aider les utilisteurs avancés à accomplir une tâche correctement. Elle peut :

  • Faire une démonstration des capacités de Koha.

  • Guider vos utilisateurs vers la résolution d’un problème concret avec Koha par des étapes successives.

  • Aider à apporter une réponse aux questions précises que peuvent se poser les utilisateurs.

  • Rendre confortable l’utilisation de Koha.

  • Améliorer l’expérience utilisateur, et aider à réduire les coûts en diminuant le nombre de tickets au service Support.

Les nouveaux utilisateurs peuvent aussi bénéficier d’une procédure, à la condition qu’elle soit rédigée clairement et présente les connaissnces requises nécessaires à la réalisation de la tâche.

Avant de rédiger une procédure

Avant de commencer à travailler sur une procédure, identifier :

  • Le public ciblé ou le cadre d’utilisation de la procédure.

  • Les différents scénarios que les utilisateurs peuvent rencontrer dans l’accomplissement de la tâche. Si ceci, alors celà. Dans le cas d’une…, une autre approche serait de…

  • La manière la plus sure de réaliser une tâche. En suggérant de multiples manières de le faire, vous demandez aux utilisateurs de réfléchir aux différentes possibilités et de choisir. Epargnez-leur du temps et des efforts en éliminant les options.

  • Les scénarios possibles qu’un utilisateur peut rencontrer lors de la résolution d’une tâche et les solutions qui leur correspondent.

Les meilleures pratiques de rédaction d’une procédure

  • Abordez un objectif logique (une tâche) par procédure. Essayez d’éviter les cas dans lesquels seule une sous-section de la procédure est pertinente pour l’utilisateur.

  • Préparez les utilisateurs à l’inattendu, alertez-les de cette possibilité et proposez un soutien pour gérer ces situations. Par exemple, insérez des Avertissement, Attention ou Note, pour communiquer une information importante lors de la réalisation de la tâche.

  • Utilisez des impératifs conditionnels. Si vous voulez x, faites y. Pour accomplir w, faites z.

  • N’expliquez pas les concepts.

  • Il est parfois utile de fournir des liens vers des ressources de documentation pour plus d’information. En particulier quand l’utilisateur pourrait avoir besoin d’une mise en contexte ou d’une information conceptuelle et de documents de référence. Quoi qu’il en soit, évitez de fournir trop de liens avec votre procédure. Gardez autant que possible vos utilisateurs sur une seule page et indiquez les liens vers les ressources supplémentaires en bas de la page.

  • Evitez de sur-documenter de multiples manières d’accomplir une même tâche. S’il y a plusieurs moyen de réaliser une tâche donnée, choisissez et documentez la méthode la plus commune ou la mieux recommandée. Les méthodes supplémentaires doivent être carrément écartées ou juste mentionnées en fournissant un lien ou un document de référence.

  • Assurez-vous toujours que les étapes que vous décrivez dans votre procédure sont techniquement précises. Testez les instructions de votre procédure du début à la fin pour révéler des étapes que vous auriez omises, des détails erronées, des étapes qui ne fonctionnent pas et des lacunes qui bloqueraient les utilisateurs. S’il ne vous est pas possible de tester, demandez à un développeur, un bibliothécaire ou un expert dans le domain de vous décrire l’étape et enregistrez la démonstration, si possible.

  • Re-testez chacune des instructions après chaque sortie notable de version, pour vous assurer qu’elles sont toujours d’actualité.

  • Les procédures trop longues peuvent démotiver les utilisateurs. Concentrez votre procédure sur une seule tâche et limitez à 8-10 étapes par tâche. Si la tâche est trop importante, scindez-la en plusieurs sous-tâches logiques avec leurs propres étapes.

A propos de la section « Vue d’ensemble »

Utilisez cette section pour fournir :

  • Une description claire du problème ou de la tâche que l’utilisateur peut résoudre ou accomplir.

  • Quand et pourquoi l’utilisateur doit réaliser cette tâche. Par exemple, dans un guide pour créer une demande de tirage (pull request), vous devriez dire aux usagers que les demandes de tirage sont utilisées pour signaler les modifications que vous avez effectuées sur la branche du dépôt.

La procédure suppose que l’utilisateur dispose des connaissances de base sur Koha et sait ce qu’il souhaite obtenir.

Des exemples :

  • Ce guide explique comment ouvrir un ticket sur Bugzilla. Vous pouvez ouvrir des tickets pour suivre les bugs, améliorations, et nouvelles fonctionnalités des modules et outils de Koha.

  • Ce guide explique comment fermer temporairement une bibliothèque. Fermer temporairement une bibliothèque nécessite quelques modifications dans Koha, comme informer bibliothécaires et adhérents, mettre à jour des notifications et allonger la durée des prêts.

A propos de la section « Avant de commencer »

{Cette section est facultative}

Cette section décrit ce que vos usagers ont besoin de savoir ou d’avoir avant de suivre la procédure. En présentant les pré-requis, vous évitez à vos usagers de découvrir, à mi-parcours, qu’ils doivent arrêter pour aller lire de la documentation avant de pouvoir reprendre.

Utilisez cette section pour communiquer tous les pré-requis pour cette procédure, tels que :

  • Une certaine connaissancedu module ou de la fonctionnalité Koha

  • Toutes informations, logiciels ou outils nécessaires

  • Environnements à mettre en place et configurer

  • Informations sur les authentifications et les permissions

  • Autres guides ou informations à lire

  • Liens vers les procédures ou informations, ou n’importe quels indicateurs utiles pour obtenir ce dont ils ont besoin.

Pour faciliter la compréhension, veillez à rassembler les pré-requis en catégories comme connaissnces préalables et prérequis informatiques.

Facultativement, placez des indices afin de signaler aux utilisateurs qu’ils ne sont peut-être pas au bon endroit et offrir des options plus adaptées. Par exemple, Si vous utilisez Linux, référez-vous à {lien vers le guide de procédure Linux pertinent}.

Exemples :

Before you begin, ensure you have:

* A conceptual understanding of RESTful APIs.

Before you begin, ensure you have:

* API credentials for the v3.5 API.
* Access to the Postman application.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.

A propos de la section « Etapes »

La section Etapes est celle où vous décrivez ce que l’utilisateur doit faire. Utilisez une liste ordonnée pour documenter les étapes de la procédure. Le modèle organise les étapes de la manière suivante :

{Task name}

{Optional: Provide a concise description of the purpose of this task. Only
include this if the purpose is not clear from the task title.}

1. {Write the action to take here. Start with a verb.}

   {Optional: Explanatory text}

   {Optional: Code sample or screenshot that helps your users complete this
   step}

   {Optional: Result}

   {Optional: If needed, you can add substeps below a primary step.}

Un exemple d’étape :

Create a pull request

Pull requests are used to inform others of changes you have pushed to a
branch in a repository. Once a pull request is opened, you can collaborate
with reviewers and make changes before merging into the base branch.

1. To create a pull request:

   1.1. Navigate to the main page of your repository.

   1.2. Under your repository name, click **Pull requests**. By default, all
   open pull requests are displayed.

Si vous incluez des exemples de code dans vos étapes, veillez à bien respecter l’indentation :

  1. Configurez votre identifiant Git pour votre dépôt.

    Vous pouvez modifier le nom associé à vos commits Git en utilisant la commande git config.

    git config user.name "Dakota Everson"

Conseils de rédaction des étapes

  • Pour les noms de tâche, débutez avec l’infinitif ou ` plus précisément <https://fr.wikipedia.org/wiki/Infinitif_en_français>`_. Par exemple, « Se connecter », « Implanter », « Construire » puis exprimez le titre comme une pensée complète : « Se connecter à une instance VM ».

  • Pour chacune des étapes, vous pouvez proposer des informations de contexte sur la tâche afin que les utilisateurs sachent ce qu’ils sont en train de faire et pourquoi. Pour continuer avec l’exemple ci-dessus, vous pourriez proposer de bonnes pratiques pour créer des noms de dépôt explicites.

  • Facultativement, ajoutez un exemple de code ou des captures d’écran après les explications, selon le type de procédure que vous rédigez. Les captures d’écran sont un bon moyen d’afficher des parties précises de l’écran auquel vous vous référez à une étape. Assurez-vous que les exemples de code fonctionnent et sont toujours à jour.

  • Souvenez-vous de guider les utilisateurs quand vous les faites cheminer à travers chaque étape. S’ils ont besoin d’ouvrir un fichier en particulier ou une boîte de dialogue pour accomplir une tâche, indiquez-leur cette information en premier lieu.

  • Fournissez des exemples de résultats type comme des données obtenues ou messages afin que les utilisateurs sachent s’ils ont accompli correctement l’étape ou non. Par exemple, vous pourriez souhaiter leur montrer ce à quoi ressemble le résultat valide et attendu suite à la saisie d’une commande dans un CLI.

  • Utilisez un langage clair et expliquez les termes techniques à côté de celà.

  • N’incluez qu’une action par étape.

Pour des conseils supplémentaires sur la rédaction des étapes, voir Rédaction des étapoes procédurales.

A propos de la section « Voir aussi »

Il est probable qu’en expliquant un processus comprenant de nombeuses tâches, que vous mentionniez d’autres sujets liés au sujet initial mais pas spécialement nécessaires. Cette section est utile pour fournir à vos utilisateurs des suggestions de lectures sans toutefois interrompre le déroulé du sujet traité par le document.

Un exemple serait le paramétrage d’un client de messagerie, qui nécessite des identifiants valides pour une adresse de courriel valide. Le lecteur n’a pas besoin de savoir comment installet et exécuter son serveur de messagerie pour y avoir accès, bien que ça puisse être utile. Le lien vers la documentation couvrant l’utilisation d’un serveur local de messagerie pourrait être inclus dans la section « Voir aussi ».

Ressources additionnelles

Consultez les autres guides et modèles du The Good Docs Project.