|
|
| (2 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| [[Category:Writing Guidelines]] | | [[Category:Writing Guidelines]] |
| TODO: Check whether all these rules are listed in the [https://learn.microsoft.com/en-us/style-guide/welcome/ Microsoft Style Guide] and then remove this page.
| |
|
| |
|
| QUESTION: Should we add these as links into the appropriate sections in the MS Style Guide on the [[Developing Qt Documentation]] page?
| |
|
| |
|
| This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]. | | This page is now integrated as part of the [[Qt Writing Guidelines]]. |
| | |
| ==Idioms and usage==
| |
| | |
| ===Point of view (POV)===
| |
| | |
| Use second person point of view with the personal pronoun '''you''' in technical communication. This is also known as direct address, and helps you write in active voice.
| |
| | |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/grammar/nouns-pronouns
| |
| | |
| ===Since/as/because and ambiguity===
| |
| | |
| According to MSTP both "since" and "as" need to be avoided because they can lead to ambiguous interpretations (causal meaning or temporal meaning). MSTP recommends using "because".
| |
| | |
| The Canadian Writer's Handbook also recommends not using "since" and "as".
| |
| | |
| The Chicago Manual of Style doesn't mention this issue.
| |
| | |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences
| |
| | |
| ==Spelling==
| |
| | |
| Qt documentation follows American English spelling.
| |
| | |
| ===Latin expressions commonly used in English===
| |
| | |
| i.e. (that is)
| |
| e.g. (for example)
| |
| cf. (compare)
| |
| etc. (and so forth)
| |
| vs.(versus)
| |
| et al. (and others)
| |
| | |
| It is advisable to use the English equivalent for better readability.
| |
| | |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
| |
| | |
| ==Punctuation==
| |
| | |
| ===Oxford comma===
| |
| | |
| In punctuation, a serial comma (also called Oxford comma) needs to be placed immediately before the conjunction (often "and" or "or") in a series of three or more terms.
| |
| | |
| Example:
| |
| | |
| I would like crackers, cheese, and garlic.
| |
| | |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/punctuation/commas
| |
| | |
| ===The comma as a separator between compound sentences.===
| |
| | |
| Use commas to separate independent clauses when they are joined by any of these seven coordinating conjunctions: and, but, for, or, nor, so, yet.
| |
| | |
| However, the comma can be dropped in the following cases:
| |
| | |
| *When both independent clauses are quite short, especially if the two clauses are very closely related, and even more so if the subject of both clauses is the same.
| |
| | |
| *If only the first clause is quite short, especially if the two clauses are very closely related, and even more so if the subject of both clauses is the same.
| |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/punctuation/commas
| |
| | |
| ===Periods and spaces===
| |
| | |
| The period ending a sentence should be followed by 1 space.
| |
| | |
| An exception to this rule is the legal text in the beginning of Qt code, which can have 2 spaces after a period.
| |
| | |
| JEROME: Found in MSTP: https://learn.microsoft.com/en-us/style-guide/punctuation/periods
| |
| | |
| ==Grammar issues==
| |
| | |
| ===Genitive===
| |
| | |
| Can we use the possessive's if the owner is not a person ?
| |
| | |
| Example:
| |
| | |
| *the item's width
| |
| *the width of the item
| |
| | |
| Both are correct. There is presently no rule stating that the owner cannot be an inanimate object.
| |
| | |
| JEROME: Not Found in MSTP.
| |
| | |
| ===An URL or a URL ?===
| |
| | |
| A URL.
| |
| | |
| If the "u" is long, the article is "a". For example, a uniform, a university, a Ugandan man.
| |
| | |
| If it is short, the article is "an". For example, an understatement, an undermining comment, an underdog team.
| |
| | |
| JEROME: This is a phonetic rule. Maybe explain the phonetic rule.
| |
| | |
| ==Sources==
| |
| | |
| Microsoft Manual of Style, Fourth Edition. Microsoft Press
| |
| https://www.microsoftpressstore.com/store/microsoft-manual-of-style-9780735648715
| |
| | |
| The Chicago Manual of Style, 14th edition. The University of Chicago Press.
| |
| "English Language & Usage": http://english.stackexchange.com/about.
| |
This page is now integrated as part of the Qt Writing Guidelines.