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

  • Les copies d’écran sont placées dans le texte comme des figures et comprennent un texte alternatif si l’image ne peut pas être chargée, de même qu’une description de la figure. Cette dernière recevra la numérotation ad hoc lors de l’exportation en PDF.

  • 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 petis boutons peuvent être placés dansle texte.

  • Les copies d’écran des sections de Mahara ne sont pas placées dans le texte mais reçoivent la directive « figure ». Elles comprennent toujours un code « alt » ainsi qu’une brève description qui s’affiche au bas de l’image et est numérotée dans LaTeX PDF.

  • Les copies d’écran doivent avoir aussi peu d’instruction de pas à pas que possible. Il est préférable de n’avoir sur l’image qu’un numéro dans texte, afin qu’il soit plus facile à assurer la traduction des instructions dans plusieurs langues. Cela permet aussi aux traducteurs de modifier la traduction sans préalablement être obligés de refaire les copies d’écran.

  • Inline images that are refered to in the textsuch as edit should be included as shortcuts with the reference at the bottom of the page.

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

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

  • Les copies d’écran de la version originale du manuel ont été réalisée avec Shutter sous Ubuntu. Il est ensuite facile d’ajouter les puces numérotés pour indiquer les étapes à effectuer. Toutefois il est possible d’utiliser d’autres logiciels mais il serait bien que la couleur de la numérotation reste la même (soit #4C711D).

  • La numérotation sur les copies d’écran se réfèrent au pas-à-pas décrit sur la page.

  • Les copies d’écran ne devraient montrer que les zones importantes et non l’entier de l’écran, la barre d’adresse URL, etc.