2. Information pour les auteurs et les traducteurs du manuel pour les utilisateurs de Mahara

par Kristina D.C. Hoeppner

Je fais cette liste au fur et à mesure que je travaille sur ce manuel. Elle se prête donc à évoluer. Il y a un certain nombre de points pour lesquels j’ai créé des conventions, des normes. Je désire qu’elles restent établies et utilisées dans les différentes traductions et autre documents créés autour de Mahara. Je souhaite les laisser dans un endroit central, accessible par toutes et tous, afin que chacune et chacun puisse s’y référer.

Les points de la liste ne font pas référence à un ordre particulier

2.1. Réaliser les captures d’écran

  • sont placées dans le texte en utilisant la commande « figure ».
  • doivent toujours contenir un texte alternatif et une description afin de faciliter l’accès aux personnes souffrant de handicaps. Les copies d’écran seront numérotées automatiquement au moment de l’export en PDF. De cette façon elles sont mises en dehors du texte.
  • sont généralement placées au-dessus de la liste à puces si elles font partie d’une instruction pas à pas.
  • doivent faire référence à un minimum d’instructions, autant que possible, dans la démarche pas à pas. Il est même préférable qu’elles fassent référence qu’à un seul point, afin qu’elles puissent être échangées facilement contre un texte explicatif. Ce dernier pourra être traduit dans d’autres langues. Cela permettra donc aux traducteurs de traduire le texte, dans un premier temps, sans devoir éditer les copies d’écran immédiatement.
  • saisissez les numéros de références créés dans Gimp avec le script que Iñaki a adapté.
  • doivent contenir des numéros qui font référence aux points que l’on est en train de documenter en dessous de la figure.
  • doivent ne montrer que le strict nécessaire, et non pas tout l’écran ou la barre d’adresse, etc. quand ce n’est pas indispensable.

La plupart des copies d’écran sont ajoutés avec la commande figure

Example of including a screenshot

Exemple d’inclusion d’une copie d’écran

  1. La première ligne indique le chemin pour atteindre le fichier de l’image. Le * remplace l’extension du fichier, de ce fait Sphinx choisit le format le plus approprié pour chaque fichier. De ce fait, chaque image peut être proposée avec différentes extensions, dans différentes qualités, qui seront choisies automatiquement en fonction de l’usage et du périphérique de sortie (écran, imprimante, affichage dans le navigateur web, création d’un document PDF ou ePub).
  2. La deuxième ligne contient le texte «alt» qui sera affiché quand l’utilisateur placera sa souri au-dessus de l’image ou lorsque l’image ne sera pas affichée, notamment dans le cas où l’utilisateur accède la page avec un logiciel d’aide à la lecteur pour mal-voyant.
  3. La troisième ligne doit être placée après une ligne vide. Elle contient la description qui doit être affiché sous la copie d’écran. Lorsque un document PDF est créé à partir de la documentation sur le web, les descriptions seront numérotées de manière continue.
  4. Si vous ne désirez pas afficher toutes les informations d’un écran mais seulement le haut et le bas, vous pouvez utiliser le fichier ``z_omission.xcf``et y placer vos illustrations. La vague sinusoïdale a été créée su Gimp avec le plugin Shape paths et les paramètres suivants :
    • Sine Wave
    • Start X : 0
    • Start Y : 200 et dès la deuxième vague 215 pour assurer l’espace entre les lignes
    • Amplitude : 3
    • Wavelength : 25
    • Number of cycles : 40 (mais cela dépend avant tout de la largeur de l’image)
    • Activez «Stroke path»
    • Stroke color: CCCCCC

Note

Si vous désirez inclure une image non pas entre des lignes de texte, mais au milieux d’elles, ou que vous ne pouvez ou voulez pas utiliser la forme régulière des copies d’écran, vous devez créer une substitutions et la placer dans le fichier shortcuts.rstext.

2.2. Types d’alertes utilisées dans la documentation

  • note : pour tout ce qui doit retenir un peu plus l’attention des lecteurs

    Note

    Les notes peuvent être intégrées directement sous forme de listes à puces. Comme d’habitude, une ligne vide doit précéder et suivre la liste. La note doit être indentée par 3 espaces.

  • warning : pour tout ce qui doit être effectué et qui peut comporter un risque (par exemple : perte de donnée, impossibilité de revenir en arrière, …)

    Avertissement

    Essayez de ne pas mettre trop d’informations dans la note, car l’essentiel risque d’être alors noyé dans la masse.

  • seealso: pour renvoyer le lecteur vers d’autres parties du manuel ou de documents complémentaire qui devraient être consultés par le lecteur. Les références à ces autres documents peuvent aussi être inclues dans le texte lui-même.

    Voir aussi

    La documentation pour les utilisateurs de Sphinx est un moyen d’approfondir vos connaissances sur l’utilisation de rST avec Sphinx. Si vous avez des questions, vous pouvez aussi consulter le groupe de discussion sur Sphinx.

  • todo : pour enregistrer réglulièrement ce qu’il y a encore à faire dans la rédaction de ce présent manuel.

2.3. Conventions

  • Chaque section qui est liée à un item du menu de navigation de Mahara doit faire figurer le chemin pour l’atteindre, par exemple Contenu → Fichiers. Il est préférable que vous copiiez la flèche depuis le texte original, afin de vous assurer que vous utilisez le bon caractère.

  • Les boutons comme Enregistrer ou Copier page et aussi les sections du portfolio comme Contenu, Portfolio, etc., sont mises en évidence en corps gras (avec un seul *).

  • Des petits boutons peuvent être inclus dans le texte, comme edit, manage. Ils sont ajoutés par substitution de leur code par leur image. Toutes ces images sont placées dans le fichier shortcuts.rstext qui est inclu à chaque fichier dans lequel des substitutions doivent être faites, en plaçant la commande « .. include:: /shortcuts.rstext »i dans la première ligne du fichier. Les substitutions sont créée par le code placé directement dans le texte, par exemple : « *Edit* button |edit| ». Les traducteurs ne doivent pas modifier le code de substitution « |edit|`» mais seulement traduire «*Edit* button » en prenant soin d’ajouter le * sans laisser d’espace entre le * et le texte, pour s’assurer que le mot sera affiché en gras.

  • Une entrée d’index doit être créée pour chaque section

  • Les nouvelles fonctionnalités se trouvent dans l’index et sont signalées dans le texte par « sigle: New in Mahara 1.x, [la nouvelle fonctionnalité] ».

  • Les sections longues doivent être séparées en plusieurs pages pour faciliter l’édition du texte.

  • reStructuredText ne gère pas la hiérarchie dans le niveau d’en-têtes. Ces derniers dépendent des fichiers individuels. Toutefois, pour être cohérent, la convention suivante existe :

    • Titre 1, par ex. 1.: ===============
    • Titre 2, par ex. 1.1.: —————
    • Titre 3, par ex. 1.1.1.: ~~~~~~~~~~~~~~~
    • Titre 4, par ex. 1.1.1.1.: ^^^^^^^^^^^^^^^

  • Une structure à plus de 4 niveaux doit être évitée.

  • Les pages d’index n’ont pas d’en-tête en plus de l’en-tête principal. Cela permet d’éviter que la table des matières ainsi que les autres sections qui possèdes des en-têtes soient considérées comme les chapitres principaux du manuel. Gardez l’apparence des en-têtes de l’index en gras en utilisant **.

2.4. Formattage du texte

  • Chaque item d’une liste à puce comment par le symbole *.
  • Chaque élément d’une liste numérotée commence par #.
  • Si vous désirez créer des listes à puces à plusieurs niveaux, laissez une ligne vide entre chaque niveau et placez 3 espaces devant chaque ligne. Il n’est pas nécessaire de laisser un ligne vide lorsque vous arrivez à la fin d’une sous-liste.
  • La mise en évidence d’une partie d’un texte se fait en débutant et terminant celui-ci par 1 *, comme par exemple : *cela*. Ce qui vous donnerait quelque chose comme cela.
  • La mise en gras d’un texte commence et se termine avec 2 *, comme **cela** ce qui donne cela.

2.6. Entrées d’index

Les entrées d’index sont utilisées pour accéder rapidement à une information précise. Les entrées peuvent être créées juste au-dessus d’un en-tête ou dans le texte. Les entrées dans le texte ont l’avantage de vous amener exactement là où vous voulez vous rendre.

  • Les entrée d’index sont créées de la manière suivante : :index:`Votre image du profil <single: Nouvauté Mahara 1.10; Lien vers les image du profil>`.

2.7. Traducteurs, prêtez attention

  • Ne modifiez pas la cible des liens internes qui sont placés entre < >. Si vous le faites, les références ne seront plus trouvées. Il y a toujours un texte d’explication avant les < >, c’est ce texte que vous devez traduire.
  • De manière similaire, vous pouvez modifier le texte d’un URL mais pas l’URL lui-même, à moins que vous ne le remplaciez pour pointer sur un texte écrit dans votre langue de traduction.
  • Si vous traduisez les copies d’écran et les autres images, veillez à conserver intacte la structure du dossier « images ». Il est important que cette structure reste comme elle a été fixée dans Gitorious.
  • Vous pouvez accéder aux images originales du manuel dans le dossier « images_original » et dans les sous-dossiers correspondants. Vous pouvez les utiliser pour effectuer les traductions nécessaires si vous désirez modifier le fond en gardant la numérotation.
  • Vous n’avez pas besoin de placer dans la traduction les images que vous ne souhaitez pas traduire, par exemple les icônes des blocs, les boutons généraux et les boutons d’édition. Toute image manquante dans les dossiers de traduction sera automatiquement remplacée par la version originale en anglais.
  • Le manuel de l’utilisateur est mis à jour une fois par jour et les nouvelles traductions des chaînes de caractères sont envoyées depuis le système Launchpad dans la nouvelle version du manuel. Il en est de même des images sur le Git qui sont compilées avec la création journalière du manuel.
  • A l’heure actuelle, toutes les chaînes de caractères ne peuvent pas être traduites dans Sphinx. Il est donc normal que certaines traces du manuel original en anglais apparaissent ici ou là. Avec un peu de chance, les versions ultérieures permettront de corriger cela.

Note

Si vous désirez mentionner les noms des traducteurs qui ont participé à la traduction du manuel de l’utilisateur de Mahara dans votre langue, vous pouvez le faire en ajoutant une phrase après « Le manuel de l’utilisateur de Mahara a été écrit par les membres de la communauté ». Ce paragraphe apparaît avant la table des matières. Il n’y a pas d’équivalent à ce phrase dans la version originale anglaise, car il ne s’agit pas d’une traduction.