Guide de rédaction

Qui peut contribuer à ce wiki?

Tous les détenteurs d'un compte Calcul Canada. Il revient à l'équipe Calcul Canada de fournir une documentation complète et juste, mais nous sommes à l'ère Wikipédia. Si un utilisateur remarque un problème évident comme un lien brisé ou une coquille, il peut bien entendu le corriger. Aussi, un utilisateur qui le souhaite peut rédiger un article en rapport avec un logiciel qu'il connait bien. L'équipe de documentation Calcul Canada révisera les articles affichés par les utilisateurs pour vérifier leur conformité aux présentes directives.

La collaboration au wiki ne se fait pas de façon anonyme. Vous devez vous connecter en utilisant les coordonnées de votre compte Calcul Canada; ceci nous permet de savoir qui a rédigé ou modifié le contenu.

What belongs on this Wiki?

This Wiki is not the place for information which properly belongs in the purview of the Compute Canada executive team, particularly the Executive Director of External Affairs (henceforth called the Executive). This obviously includes any communications intended for the general public, media or funding agencies. Materials related to training and outreach also don’t belong on this technical documentation site. To that end, ask yourself before you publish a page or make a change:

• Is this about what services or clusters are available? If so, has the service or cluster already been announced? If not, consult the Executive before publishing.
• Status information which changes on short notice --- available, offline, in maintenance, etc.--- will likely be the responsibility of the Monitoring Team.
• Is this information useful to a user, as opposed to other CC technical staff? If technical staff, then it might belong at https://wiki.computecanada.ca/staff/ rather than https://docs.computecanada.ca/wiki/.
• Does the information have implications for the security of our systems, or data on our systems? If so, consult the Director of Information Security before publishing.
• Is the information of interest only to a prospective user, as opposed to an existing account-holder? This is a gray area: A prospective user might want to know technical details about our services and facilities, the same as an account-holder, but if the information is only of interest to a prospective user then it properly belongs on https://computecanada.ca rather than https://docs.computecanada.ca/wiki/.
• External links may be appropriate, see e.g. "Getting an Account".
• Is this about how to use an existing service, cluster, or application? If so, go ahead.

Guide de style

Rédaction

Le guide de style aide les rédacteurs à produire une documentation technique qui facilite l'apprentissage. Une documentation bien préparée est agréable au lecteur et projette une image positive de l'auteur. Il existe plusieurs guides de style pour la documentation technique. L'Office québécois de la langue française en liste quelques-uns. Calcul Canada n'a pas encore de guide de style, mais il est important de retenir certaines pratiques usuelles :

• Énoncer une idée principale par paragraphe.
• Placer l'information en ordre d'importance.
• Adressez-vous directement au lecteur.

Par exemple : Cliquez sur le bouton plutôt que L'utilisateur doit cliquer sur le bouton.

• Utilisez le plus possible un vocabulaire courant et simple.
• Construisez vos phrases avec des verbes au présent.
• Utilisez la voix active.

Par exemple : Le fichier contient les paramètres valides plutôt que  Les paramètres valides sont contenus dans le fichier.

• Utilisez la forme positive.

Par exemple : Répondre OUI plutôt que Ne pas répondre NON.

• Employez le mot juste.

Bien sûr, les synonymes rendent le texte moins ennuyant, mais ils peuvent créer de la confusion chez un nouvel utilisateur ou un utilisateur dont la langue maternelle est différente de celle du texte (par exemple, machine, hôte, noeud, serveur).

Mise en page

Si vous doutez, imitez les maitres. Utilisez le style d'une page existante. Si vous n'en trouvez pas sur docs.computecanada.ca, cherchez sur Wikipédia.

• Autant que possible, gardez les images à part du contenu texte. N'utilisez pas des sauts de ligne pour ajuster l'espacement vertical. N'utilisez pas la tabulation ou des espaces pour mettre un paragraphe en retrait; n'ajoutez pas d'espace à la fin d'une phrase. Si ce type de formatage est souhaitable, nous préparerons des feuilles de style ou des gabarits, le cas échéant.
• Les captures d'écran sont utiles, surtout dans le cas de guides d'utilisation ou de tutoriels. Cependant, les captures plein écran incluses dans le texte nuisent à la lisibilité. Placez les images flottantes à la droite du texte. Réduisez aussi la taille de l'image. Si la visibilité n'est pas acceptable, peut-être devriez-vous rogner l'image? Vous pouvez aussi ajouter la mention Cliquez pour agrandir.
• Employez le moins de synonymes possible. Bien sûr, les synonymes rendent le texte moins ennuyant, mais ils peuvent créer de la confusion chez un nouvel utilisateur ou un utilisateur dont la langue maternelle est différente de celle du texte (par exemple, machine, hôte, nœud, serveur).
• Laissez une ligne vide à la fin d'une section, avant le titre de la prochaine section. La fonction de traduction utilise la ligne vide et le titre pour délimiter les unités de traduction.

Gabarits

Plusieurs gabarits sont disponibles. Veuillez les utiliser au besoin. Nous attirons votre attention sur les gabarits pour Inclure une commande dans une page wiki et Inclure un fichier de code source dans une page wiki.

Traduction

La page dans la langue source doit être marquée pour la traduction. Toute personne peut traduire une page marquée pour traduction avec les outils de l'extension wiki Traduire. Vous trouverez un tutoriel ici. Une page traduite peut ensuite être révisée.

Lorsqu'une page est marquée pour la traduction, l'extension Traduire analyse son contenu et le divise en unités de traduction qui sont par exemple un titre, un paragraphe, une image ou autre. Les unités discrètes sont traduites individuellement : ainsi, une modification à une unité n'a pas d'effet sur le reste de la page et il est possible de connaitre le pourcentage de la page déjà traduit ou devant être mis à jour.

Marquer une page pour la traduction

1. Le contenu à traduire doit être compris entre les codes <translate> </translate>.
2. Le code <languages /> doit paraitre au tout début de la page.
3. En mode View, cliquez sur Marquer cette page pour la traduction.
4. Effectuez la traduction des unités en évitant de modifier les codes wiki.
5. Sélectionnez la langue prioritaire pour la traduction; il s'agit de la langue cible.
6. Cliquez sur Marquer cette page pour la traduction.

Identifier les modifications dans une page marquée pour la traduction

Il est recommandé de marquer une page pour la traduction une fois que le contenu en langue source est stable. Si une page déjà traduite ne comporte pas de changements, évitez de modifier les codes tels que <!--T:3-->, qui sont des codes générés automatiquement.

Une fois la page corrigée, marquez les modifications à traduire comme suit :

1. Le nouveau contenu à traduire doit être compris entre les codes <translate> </translate>.
2. En mode View, un message au haut de la page vous informe que la page comporte des modifications faites après qu'elle ait été marquée pour la traduction.
3. Effectuez la traduction des unités en évitant de modifier les codes wiki.
4. Sélectionnez la langue prioritaire pour la traduction; il s'agit de la langue cible.
5. Cliquez sur Marquer cette page pour la traduction.