39,881
edits
Authoring guidelines/en: Difference between revisions
Jump to navigation
Jump to search
Updating to match new version of source page
(Updating to match new version of source page) Tags: Mobile edit Mobile web edit |
(Updating to match new version of source page) |
||
| Line 48: | Line 48: | ||
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]]. | 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. | ||
* | * Screenshots are good, especially in how-tos and tutorials. But full-sized screenshots 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. | ||