Authoring guidelines/fr: Difference between revisions

From Alliance Doc
Jump to navigation Jump to search
(Updating to match new version of source page)
No edit summary
Line 15: Line 15:
* L'information explique-t-elle comment utiliser une grappe, une application ou un service existants? Si c'est le cas, allez-y.
* L'information explique-t-elle comment utiliser une grappe, une application ou un service existants? Si c'est le cas, allez-y.


== Style guidelines ==
==Guide de style==  
=== Writing style ===
=== Rédaction ===
The purpose of a style guide is to support writers in preparing technical documentation that makes learning easier. Carefully crafted documentation appeals to the user and delivers a positive image of the writer.
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.
There are several style guides in circulation that set standards for computer documentation. Pioneers in this area are the Apple Style Guide and the Microsoft Manual of Style.
Il existe plusieurs guides de style pour la documentation technique. L'Office québécois de la langue française en liste quelques-uns.
There are no official writing guidelines for Compute Canada, but here are some simple and common practices we can readily adopt:
Calcul Canada n'a pas encore de guide de style, mais il est important de retenir certaines pratiques usuelles :
* Design each paragraph around one idea.
* Énoncer une idée principale par paragraphe.
* Present the most important information first.
* Placer l'information en ordre d'importance.
* Address the reader directly.
* Adressez-vous directement au lecteur.
: Example: ''The user must click on the button'' or ''One must click on the button'' becomes ''Click on the button.''
: Par exemple : Cliquez sur le bouton plutôt que L'utilisateur doit cliquer sur le bouton.
* Use [http://www.plainlanguage.gov/howto/wordsuggestions/simplewords.cfm simple words and phrases].
* Utilisez le plus possible un vocabulaire courant et simple.
* Use the present tense.
* Construisez vos phrases avec des verbes au présent.
: Example: ''Doing this will launch the XYZ application'' becomes ''This launches the XYZ application.''
: Par exemple :
* Use the active voice.
* Utilisez la voix active.
: Example: ''The file is edited by the system administrator'' becomes ''The system administrator edits the file.''
: Par exemple : Le fichier contient les paramètres valides plutôt que  Les paramètres valides sont contenus dans le fichier.
* Stay positive.
* Utilisez la forme positive.
: Example: ''Don't use the passive voice'' becomes ''Use the active voice.''
: Par exemple : Répondre OUI plutôt que Ne pas répondre NON.
* Use consistent terms.  
* Employez le mot juste.  
: Yes, synonyms make a text less boring, but for a new user or one reading in a second language, interchangeable terms (e.g. "machine", "host", "node", "server") may be confusing.
: 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'').
=== Layout style ===
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.   
When in doubt, imitate the masters. Look at an existing page you like and follow the style. If there isn’t one at docs.computecanada.ca, look for one at Wikipedia.   
* 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.
* Separate graphic design from content as much as possible. Don’t use extra line breaks to adjust vertical spacing. Don’t indent paragraphs with tabs or spaces or add extra spaces after a sentence. If we want to make any such style adjustments we will make them universally using stylesheets and templates.
* 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''.
* Screen shots are good, especially in how-tos and tutorials. But full-sized screen shots interrupt the structure and flow of the text if they’re placed in-line. Let them float to the right-hand side. Also, scale the image down. If that makes important information unreadable, maybe a cropped picture is better? Or, remind the reader in the caption that they can "Click on the image for a larger version."
* 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'').
* Leave one blank line at the end of each section before the following header. The translation package uses the blank line and header to determine the boundaries of translation units.
 
* Links to other pages or sites should have a human-oriented description for display rather than the raw URL.  
 
 
* 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 ===
=== Gabarits ===

Revision as of 20:32, 14 July 2016

Other languages:

Who can contribute to this Wiki?

Anyone with a Compute Canada account. CC staff members have the primary responsibility to keep the documentation complete and correct, but this is the age of Wikipedia. An ordinary user who spots an obvious problem, like a dead link or a typographical error, is welcome to fix it. Equally so, a user who is willing to write an entire page on some piece of installed software with which they are very familiar, is also welcome to do that. The Compute Canada documentation team will review it once it’s posted to see that it meets these guidelines.

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.

Contenu du wiki

Ce wiki n'est pas l'endroit où afficher l'information qui relève de la responsabilité de la direction de Calcul Canada, particulièrement de la responsabilité de la directrice générale des Affaires extérieures (ci-après la directrice). Ceci inclut toute information pour communication au grand public, aux médias et aux agences de financement. L'information touchant les activités de formation et de rayonnement ne conviennent pas au contenu de ce wiki pour la documentation technique. Avant de publier une page ou de modifier le contenu du wiki, posez-vous les questions suivantes :

  • Cette information est-elle au sujet de la disponibilité d'une grappe ou d'un service? Si c'est le cas, cette grappe ou ce service a-t-il fait l'objet d'une annonce? Autrement, communiquez avec la directrice avant de publier.
  • L'information sur un état susceptible de changer à court terme (disponible, hors ligne, en maintenance, etc.) est probablement sous la responsabilité de l'équipe de suivi.
  • L'information s'adresse-t-elle aux utilisateurs ou à d'autres membres des équipes techniques de Calcul Canada? Si elle s'adresse à une équipe technique, elle devrait se trouver sur https://ccdb.computecanada.ca/wiki/ plutôt que sur https://docs.computecanada.ca/wiki/.
  • Cette information a-t-elle une incidence sur la sécurité de nos systèmes ou des données sur nos systèmes? Si c'est le cas, communiquez avec le directeur de la sécurité de l'information avant de publier.
  • L'information s'adresse-t-elle à un utilisateur potentiel plutôt qu'à un détenteur de compte? Il y a ici une zone grise : un utilisateur potentiel pourrait vouloir connaitre les détails techniques en rapport avec nos services et nos sites, tout comme un détenteur de compte. Cependant, si l'information n'est d'intérêt que pour un utilisateur potentiel, elle devrait se retrouver sur https://computecanada.ca plutôt que dans https://docs.computecanada.ca/wiki/.
  • Il est approprié de publier des liens externes; voir par exemple Obtenir un compte.
  • L'information explique-t-elle comment utiliser une grappe, une application ou un service existants? Si c'est le cas, allez-y.

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.
Par exemple :
  • 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).

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.

Translation

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.
Retrieved from "https://docs.alliancecan.ca/mediawiki/index.php?title=Authoring_guidelines/fr&oldid=2151"