Language Guidelines: Difference between revisions
Paulwicking (talk | contribs) m (Remove style guide recommendation as it is now on the Developing Documentation page (further up the hierarchy)) |
(Suggestions for updating the doc guidelines.) |
||
| 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 part of the [[QtWritingGuidelines | Qt Writing Guidelines]]. | ||
== Idioms and usage == | ==Idioms and usage== | ||
=== Point of view (POV) === | ===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. | 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. | ||
=== Since/as/because and ambiguity === | ===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". | 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". | ||
| Line 19: | Line 23: | ||
http://grammar.quickanddirtytips.com/although-versus-while.aspx . | http://grammar.quickanddirtytips.com/although-versus-while.aspx . | ||
== Spelling == | ==Spelling== | ||
Qt documentation follows American English spelling. | Qt documentation follows American English spelling. | ||
=== Latin expressions commonly used in English === | ===Latin expressions commonly used in English=== | ||
i.e. (that is) | i.e. (that is) | ||
| Line 34: | Line 38: | ||
It is advisable to use the English equivalent for better readibility. | It is advisable to use the English equivalent for better readibility. | ||
== Punctuation == | ==Punctuation== | ||
=== Oxford comma === | ===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. | 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. | ||
| Line 44: | Line 48: | ||
I would like crackers, cheese, and garlic. | I would like crackers, cheese, and garlic. | ||
=== The comma as a separator between compound sentences. === | ===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. | Use commas to separate independent clauses when they are joined by any of these seven coordinating conjunctions: and, but, for, or, nor, so, yet. | ||
| Line 50: | Line 54: | ||
However, the comma can be dropped in the following cases: | 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. | *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. | *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. | ||
=== Periods and spaces === | ===Periods and spaces=== | ||
The period ending a sentence should be followed by 1 space. | The period ending a sentence should be followed by 1 space. | ||
| Line 60: | Line 64: | ||
An exception to this rule is the legal text in the beginning of Qt code, which can have 2 spaces after a period. | An exception to this rule is the legal text in the beginning of Qt code, which can have 2 spaces after a period. | ||
== Grammar issues == | ==Grammar issues== | ||
=== Genitive === | ===Genitive=== | ||
Can we use the possessive 's if the owner is not a person ? | Can we use the possessive 's if the owner is not a person ? | ||
Example: | Example: | ||
* the item's width | |||
* the width of the item | *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. | Both are correct. There is presently no rule stating that the owner cannot be an inanimate object. | ||
=== An URL or a URL ? === | ===An URL or a URL ?=== | ||
A URL. | A URL. | ||
| Line 80: | Line 85: | ||
If it is short, the article is "an". For example, an understatement, an undermining comment, an underdog team. | If it is short, the article is "an". For example, an understatement, an undermining comment, an underdog team. | ||
== Sources == | ==Sources== | ||
Microsoft Manual of Style, Fourth Edition. Microsoft Press | Microsoft Manual of Style, Fourth Edition. Microsoft Press | ||
Revision as of 15:09, 7 March 2023
TODO: Check whether all these rules are listed in the 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 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.
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.
A very good article in this respect is Grammar Girl's discussion of this topic: http://grammar.quickanddirtytips.com/although-versus-while.aspx .
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 readibility.
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.
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.
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.
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.
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.
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.