cc_staff
318
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
→Layout style
| Line 36: | Line 36: | ||
: 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 === <!--T:5--> | === Templates === <!--T:5--> | ||