38,789
edits
Authoring guidelines/fr: Difference between revisions
Jump to navigation
Jump to search
Updating to match new version of source page
No edit summary |
(Updating to match new version of source page) |
||
| 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 == | ||
=== | === Writing style === | ||
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. | |||
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. | |||
There are no official writing guidelines for Compute Canada, but here are some simple and common practices we can readily adopt: | |||
* | * Design each paragraph around one idea. | ||
* | * Present the most important information first. | ||
* | * Address the reader directly. | ||
: Example: ''The user must click on the button'' or ''One must click on the button'' becomes ''Click on the button.'' | |||
* | * Use [http://www.plainlanguage.gov/howto/wordsuggestions/simplewords.cfm simple words and phrases]. | ||
* | * Use the present tense. | ||
* | : Example: ''Doing this will launch the XYZ application'' becomes ''This launches the XYZ application.'' | ||
* Use the active voice. | |||
* | : Example: ''The file is edited by the system administrator'' becomes ''The system administrator edits the file.'' | ||
* Stay positive. | |||
* | : Example: ''Don't use the passive voice'' becomes ''Use the active voice.'' | ||
* Use consistent terms. | |||
=== | : 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. | ||
=== Layout style === | |||
* | 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 [http://www.wikipedia.org Wikipedia]. | ||
* | * 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. | ||
* | * 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." | ||
* | * 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. | |||
* 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 [https://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_(capitalization) Wikipedia], we prefer [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 === | ||