cc_staff
213
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
m
screen shots -> screenshots
No edit summary |
m (screen shots -> screenshots) |
||
| Line 51: | Line 51: | ||
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. | ||