2. Information pour les rédacteurs de documentation sur Mahara

Voici la liste de mes travaux en cours sur la documentation. Je propose des normes et des recommandations sur un certain nombre de choses. Je désire les centraliser dans un seul endroit où d’autres contributeurs pourront s’y référer. ;-)

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

  • Copies 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.
    • sont créées avec Shutter sous Ubuntu. C’est facile à faire, de plus le logiciel ajoute automatiquement les numéros qui renvoient aux points que l’on est en train de documenter. Bien que d’autres outils de copie d’écran peuvent être utilisés, veillez toutefois à garder une constance dans les copies d’écran et dans la numérotation. La couleur utilisée est #4C711D.
    • 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.

  • Les encadrés sont à utiliser pour :

    • note : pour tout ce qui doit retenir l’attention de l’utilisateur
    • alerte: pour ce qui doit être traité avec précaution
    • voir aussi : pour référencer les autres documents qui pourraient intéresser l’utilisateur. Des références à d’autres documents peuvent aussi être intégrées directement dans le texte.
    • à faire : pour créer une liste de choses à faire

  • 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 ensuite au texte par substitution. Tous les remplacements sont conservés dans le fichier shortcuts.rstext » qui est inclus au début de chaque fichier pour lequel des substitutions ont été effectuées. Ces dernières sont référencées dans le texte par exemple comme « *bouton d’Edition edit« , afin de signifier l’action que l’on peut effectuer avec ces boutons.

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

  • Les nouvelles fonctionnalités sont listées dans l’index dans la forme : « unique: Nouveau dans Mahara 1.5;[explication de ce qui est nouveau] »

  • Les sections importantes doivent être divisées en plusieurs pages, afin de les rendre plus faciles à modifier et à gérer.

  • 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.