Bureaucrats, cc_docs_admin, cc_staff
2,774
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
Add writing style suggestions
(Marked this version for translation) |
(Add writing style suggestions) |
||
| Line 18: | Line 18: | ||
== Style guidelines == <!--T:4--> | == Style guidelines == <!--T:4--> | ||
=== 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 docs.computecanada.ca, look for one at Wikipedia. | When in doubt, imitate the masters. Look at an existing page you like and follow the style. If there isn’t one at docs.computecanada.ca, look for one at 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. | ||
=== Templates === <!--T:5--> | === Templates === <!--T:5--> | ||
There are multiple [[Special:UncategorizedTemplates|templates]] | There are multiple [[Special:UncategorizedTemplates|templates]] available. Please use them as appropriate. Of particular interest are templates for [[Including a command within the wiki]] and for [[Including a source code file within the wiki]]. | ||
= Translation = <!--T:6--> | = Translation = <!--T:6--> | ||