Faire des phrases simples et courtes

L'écriture dans un livre informatique pédagogique doit être réalisée avec des phrases courtes et simples. Cela rejoint l'écriture pour le web. Plus les phrases sont longues alambiquées, plus l'utilisateur sera gêné et il devra alors relire une fois, deux fois la phrase avant de la comprendre. Tout cela nuit à la compréhension rapide d'un texte.

Voilà un exemple d'une phrase un peu trop complexe à mon goût, extraite d'un livre sur l'utilisation du logiciel Adobe Dreamweaver. C'est une explication sur la façon d'annuler l'application d'un style CSS :
"Pour annuler l'application d'un style, sélectionnez l'élément qui utilise ce style puis choisissez Format - Styles CSS - Aucun ou dans le menu déroulant Règle cible (ou Classe) du panneau Propriétés, cliquez sur Supprimer la classe ou dans le menu déroulant Classe cliquez sur Aucune".
Ouf ! Maintenant vous pouvez respirer !

Alors analysons cette phrase.

- Cette phrase comporte 46 mots ! C'est beaucoup trop. Pour moi, il faut compter 20-25 mots par phrase.

- La phrase contient trois fois le mot ou. C'est un indicateur très précis d'une phrase trop longue. A partir du moment où vous utilisez plusieurs fois le mot "ou", cela doit être un indicateur pour vous dire "Ma phrase est trop longue. Est-ce que je peux en faire plusieurs à chaque utilisation du mot ou". J'ajoute que l'utilisation du mot "puis", dans ce contexte, donne le même effet que le mot "ou".

- Le rédacteur écrit : "Règle cible (ou Classe)". Là c'est une erreur pédagogique. De quoi parle-t-on ? D'une Règle cible ou d'une Classe ? Cela ne peut pas être les deux en même temps. Si c'est l'un ou l'autre, il faut alors en expliquer le contexte d'utilisation : quand devons-nous utiliser une Règle cible ou une Classe ? A la lecture de cette phrase l'utilisateur est incapable de savoir quand il doit passer par Règle cible ou Classe.

- Puis nous lisons ensuite que cela ce passe dans le panneau Propriétés. Il eut fallut le dire avant ! Il faut toujours situer l'environnement d'utilisation avant de parler d'un élément d'interface de cet environnement (voir l'article Le chemin d'accès aux éléments d'interface).

Voilà ce que je propose comme correction :
"Pour annuler l'application d'un style, sélectionnez l'élément qui utilise ce style. Dans le panneau Propriétés, avec le bouton CSS actif, dans la liste déroulante Règle cible, choisissez Supprimer la classe. Toujours dans le panneau Propriétés, avec le bouton HTML actif, dans la liste déroulante Classe, choisissez Aucune."
J'ai ainsi trois phrases de 14, 19 et 17 mots.
Je n'ai pas utilisé les mots "ou" et "puis".
J'ai bien indiqué d'abord l'environnement dans le quel le lecteur va trouver les éléments décrits : le panneau Propriétés et après les éléments d'interface de ce panneau.
J'ai bien indiqué le contexte d'utilisation des deux possibilités pour annuler le style : avec le bouton CSS ou avec le bouton HTML actif.

Rappel à une fonction, une option

Dans une page constituée de plusieurs paragraphes, le rédacteur peut évoquer plusieurs fois une fonction, une commande, une option donnée.

A la première évocation de cette fonction, il faut clairement la décrire et correctement la nommer, avec le même nom que dans l'application, le logiciel étudié.

Quand nous devons de nouveau évoquer cette fonction, il faut impérativement la nommer de la même façon que la première fois. Il ne faut surtout pas mettre en difficulté le lecteur en changeant son nom.

De plus, nous ne devons pas l'évoquer en utilisant un mot "passe-partout" dénué de sens, type : "cette option", "cette fonction" ou "cette commande". Le lecteur ne pourra pas facilement faire le lien entre ces mots "passe-partout" et le nom de la fonction que nous souhaitons évoquer de nouveau.

Il faut toujours faire appel à une fonction en l'évoquant par son nom utilisé dans l'application.

Même mot pour la même action

A la rédaction d'un livre, il faut bien faire attention à toujours utiliser le même mot pour la même action.

Je vais prendre un exemple bien concret que j'ai déjà vu dans un (des) livre(s) : le mot choisi pour désigner l'action d'utilisation d'un item d'un menu. Dans le même ouvrage, j'ai noté tous ces mots :

• choisir,
• cliquer,
• sélectionner,
• pointer,
• activer.

Soit cinq mots différents pour la même action ! Cela nuit à compréhension de ce qu'il y a à faire. Pourquoi utiliser cinq mots différents pour la même action ? Quelle est la justification de ce manque flagrant d'homogénéité ? Le lecteur débutant peut facilement se perdre.

Donc soyons clairs : utilisez le même mot pour la même action. Vous gagnerez en simplicité et en compréhension pour vos lecteurs.

Le manque de cohérence de l'interface des logiciels (3)

Un dernier billet (?) sur Adobe Dreamweaver et son manque de cohérence dans son interface

Ces billets ne sont pas une attaque en règle contre ce logiciel (que j'utilise professionnellement et sur lequel j'ai écrit plusieurs ouvrages), mais ils sont faits pour mettre en exergue la problématique du rédacteur face à des situations pas toujours simples à résoudre : comment faire passer simplement le message aux lecteurs-utilisateurs que pour une même fonction plusieurs libellés peuvent être utilisés ?

Prenons pour nouvel exemple les formulaires qui permettent de saisir des informations et de faire divers choix. Pour insérer un élément de choix (champ de texte, bouton radio, liste...) Dreamweaver utilise des identifiants (attribut id en code HTML). Dans la boîte de dialogue qui apparaît quand nous insérons un élément de formulaire, le champ de saisie ID a deux usages !
Quand il s'agit d'un Champ de texte, d'une Liste, d'un Menu... la saisie indiquée dans le champ ID sert bien à identifier de manière unique l'élément inséré. Par contre quand il s'agit d'un bouton radio la saisie du champ ID sert aussi à indiquer la valeur à envoyer au script serveur qui gère les données du formulaire.
Le problème est bien là : un champ de saisie pour deux usages différents que rien ne différencie dans la boîte de dialogue. Ce n'est pas si simple à expliquer et à utiliser pour le débutant.

Deuxième exemple : une des techniques de mise en page des pages web utilise des "boîtes en position absolue" (boîte

en HTML). Avec Dreamweaver, cette technique s'appelle "les éléments en position absolue", les éléments PA. C'est par ce libellé, Elément PA, dans le menu et dans le panneau Insertion que nous pouvons y accéder. Mais, pour paramétrer cet élément PA, dans le panneau Propriétés, cela s'apelle Elément CSS-P.

Toujours le même problème...

Toujours faire appel à des fonctionnalités connues

Dans un livre, nous devons toujours faire appel à des fonctionnalités déjà étudiées, déjà connues.

Nous ne devons pas faire appel, ou parler d'une fonction que le lecteur verra plus tard : dans un paragraphe ou un chapitre suivant par exemple. Il n'est pas rare de lire une phrase contenant une fonctionnalité, un menu, une fenêtre, une technique que le lecteur connaîtra plus tard en lisant la suite de l'ouvrage.

Par exemple, j'ai déjà lu ce genre de phrase : "Dans cette fenêtre, vous pouvez aussi ouvrir un modèle : cliquez sur l'option Modèle". Et de me dire : "Qu'est ce qu'un modèle ?". Pas un mot, pas une référence à la notion de modèle avant d'avoir lu cette phrase ! Et même immédiatement après, pas d'explication. Comment le lecteur peut savoir à l'avance ce qu'est un modèle ? S'il faut qu'il lise dix paragraphes ou qu'il atteigne le chapitre suivant avant de d'aborder cette notion, c'est perdu. Il faudra alors qu'il revienne x pages en arrière pour retrouver la première référence à cette notion de modèle. Ce n'est pas pédagogique.

Le minimum que l'auteur puisse faire, c'est écrire explicitement que cette notion sera vue à telle page dans tel chapitre. Mais personnellement je pense que cela n'est jamais judicieux d'imposer des allers et des retours dans un livre.

C'est bien à l'auteur d'écrire sur des fonctionnalités vues et connues du lecteur. A l'auteur de structurer son ouvrage pour éviter ce type de maladresse rédactionnelle.