Language Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
m (Remove style guide recommendation as it is now on the Developing Documentation page (further up the hierarchy))
(Condensed the sections and gave links to the MS guide)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Writing Guidelines]]
[[Category:Writing Guidelines]]
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].
This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]].  


== Idioms and usage ==


=== Point of view (POV) ===
We use the [https://learn.microsoft.com/en-us/style-guide/welcome/ Microsoft Writing Style Guide] in the Qt documentation. Essentially, use clear and direct language in '''American English'''. We write to a diverse audience and we need to communicate Qt topics in an approachable and understandable manner.


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 ===
Here are some clarifications for Qt documentation:


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".
# Use '''active voice''', not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See [https://learn.microsoft.com/en-us/style-guide/grammar/verbs Verbs]
# Use the pronoun '''you''' in to address the reader when appropriate. See [https://learn.microsoft.com/en-us/style-guide/grammar/nouns-pronouns Nouns and Pronouns].
# Use '''because''' instead of "since" or "as". See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences Use simple words, concise sentences].
# Use a serial comma, also known as the '''Oxford comma'''. See [https://learn.microsoft.com/en-us/style-guide/punctuation/commas Commas]
# Use US spelling and avoid latin abbreviations. See [https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words Use US spelling and avoid non-English words]. Here is a summary :


The Canadian Writer's Handbook also recommends not using "since" and "as".
{| class="wikitable"
 
|+
The Chicago Manual of Style doesn't mention this issue.
!Use
 
!Instead of
A very good article in this respect is Grammar Girl's discussion of this topic:
!
http://grammar.quickanddirtytips.com/although-versus-while.aspx .
!
 
|-
== Spelling ==
|for example
 
|e.g.
Qt documentation follows American English spelling.
|
 
|
=== Latin expressions commonly used in English ===
|-
 
|that is
i.e. (that is)
|i.e.
e.g. (for example)
|
cf. (compare)
|
etc. (and so forth)
|-
vs.(versus)
|namely
et al. (and others)
|viz.
 
|
It is advisable to use the English equivalent for better readibility.
|
 
|-
== Punctuation ==
|therefore
 
|ergo
=== 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.

Latest revision as of 12:04, 10 October 2024

This page is part of the Qt Writing Guidelines.


We use the Microsoft Writing Style Guide in the Qt documentation. Essentially, use clear and direct language in American English. We write to a diverse audience and we need to communicate Qt topics in an approachable and understandable manner.


Here are some clarifications for Qt documentation:

  1. Use active voice, not passive. Passive does not make a sentence formal, but unnecessarily weakens the sentence. See Verbs
  2. Use the pronoun you in to address the reader when appropriate. See Nouns and Pronouns.
  3. Use because instead of "since" or "as". See Use simple words, concise sentences.
  4. Use a serial comma, also known as the Oxford comma. See Commas
  5. Use US spelling and avoid latin abbreviations. See Use US spelling and avoid non-English words. Here is a summary :
Use Instead of
for example e.g.
that is i.e.
namely viz.
therefore ergo
Retrieved from "https://wiki.qt.io/index.php?title=Language_Guidelines&oldid=42963"