38,760
edits
Authoring guidelines/en: Difference between revisions
Jump to navigation
Jump to search
Updating to match new version of source page
m (FuzzyBot moved page Authoring Guidelines/en to Authoring guidelines/en without leaving a redirect: Part of translatable page "Authoring Guidelines".) |
(Updating to match new version of source page) |
||
| Line 34: | Line 34: | ||
: 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. | : 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 === | === 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 [ | 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]]. | ||
* 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. | * 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." | * 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. | * 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. | * 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 [ | * 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. | ||
=== Templates === | === Templates === | ||
| Line 55: | Line 55: | ||
#Ensure that the tag <languages /> appear at the very top of the page. This will show a box with the list of languages the page is translated into. | #Ensure that the tag <languages /> appear at the very top of the page. This will show a box with the list of languages the page is translated into. | ||
#Go in “View” mode, and then click on the “Mark this page for translation” | #Go in “View” mode, and then click on the “Mark this page for translation” | ||
#Review the translation units. | #Review the translation units. Try to ensure that no wiki code (tables, tags, etc) gets translated. This can be done by breaking the page in multiple <translate> </translate> sections. | ||
#In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated. | #In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated. | ||
#Click on “Mark this version for translation” | #Click on “Mark this version for translation” | ||
| Line 67: | Line 66: | ||
#Ensure that the new text to be translated is enclosed within <translate> </translate> tags. | #Ensure that the new text to be translated is enclosed within <translate> </translate> tags. | ||
#Go in “View” mode. You should see the text “This page has changes since it was last marked for translation.” at the top of the page. Click on “marked for translation”. | #Go in “View” mode. You should see the text “This page has changes since it was last marked for translation.” at the top of the page. Click on “marked for translation”. | ||
#Review the translation units. | #Review the translation units. Try to ensure that no wiki code (tables, tags, etc) gets translated. This can be done by breaking the page in multiple <translate> </translate> sections. | ||
#In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated. | #In the “Priority languages” section, write either “fr” or “en” as the priority language, that is, the language into which it needs to be translated. | ||
#Click on “Mark this version for translation” | #Click on “Mark this version for translation” | ||