Authoring guidelines/fr: Difference between revisions

Jump to navigation Jump to search
Created page with "=== 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..."
(Created page with "=== Ébauches === Si vous développez une nouvelle page et qu'elle n'est pas complète, vous devriez marquer la page comme une ébauche en insérant <pre> {{Ebauche}} </pre>")
(Created page with "=== 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...")
Line 26: Line 26:
</pre>
</pre>


=== 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.''
* Utilisez la voix active.
* Use the active voice.
: Par exemple: Le fichier contient les paramètres valides plutôt que  Les paramètres valides sont contenus dans le fichier.
: Example: ''The file is edited by the system administrator'' becomes ''The system administrator edits the file.''
* Utilisez la forme positive.
* Stay positive.
: Par exemple: Répondre OUI plutôt que Ne pas répondre NON.
: Example: ''Don't use the passive voice'' becomes ''Use the active voice.''
* Employez le mot juste.  
* Use consistent terms.  
: 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'').
: 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.
=== Mise en page ===
=== Layout style ===
Si vous doutez, imitez les maitres. Utilisez le style d'une page existante. Si vous n'en trouvez pas sur [http://docs.computecanada.ca docs.computecanada.ca], cherchez sur [http://www.wikipedia.org 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 [http://docs.computecanada.ca docs.computecanada.ca], look for one at [[wikipedia: | 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.
* 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.
* Links to other pages or sites should have a human-oriented description for display rather than the raw URL.
* Capitalize only the first word and [http://blog.apastyle.org/apastyle/2012/02/do-i-capitalize-this-word.html proper nouns] in titles and headings. Following [[wikipedia:Naming_conventions_(capitalization) | Wikipedia]], we prefer the [http://blog.apastyle.org/apastyle/2012/03/title-case-and-sentence-case-capitalization-in-apa-style.html APA sentence case] for all titles, including page titles.


=== Gabarits ===
=== Gabarits ===
Bureaucrats, cc_docs_admin, cc_staff, rsnt_translations
2,837

edits

Navigation menu