From 999e1bcd86d7b19b9d9aaea8b5deca8d8c353be2 Mon Sep 17 00:00:00 2001
From: Bill <71807482+mst3k4ever@users.noreply.github.com>
Date: Fri, 9 Jul 2021 18:55:48 -0400
Subject: [PATCH] Update references.md
Updates and edits. Some structural changes to consider.
---
_content/references.md | 90 +++++++++++++-----------------------------
1 file changed, 28 insertions(+), 62 deletions(-)
diff --git a/_content/references.md b/_content/references.md
index 6da993e..8725bc5 100644
--- a/_content/references.md
+++ b/_content/references.md
@@ -1,13 +1,13 @@
## References
-This section lists commonly used units of measure, acronyms and writing issues.
+This section lists commonly used units of measure, acronyms and writing issues. //TODO William Replace with "This section lists Agora product naming guidelines, as well as commonly used units of measure and acronyms."
-For a list of the preferred style choices of terms commonly used in Agora technical documentation, refer to the [](word-list.md).
+For a list of the preferred style choices of terms commonly used in Agora technical documentation, see [](word-list.md).
-(ref/units)=
-### Commonly used units of measure and their abbreviated form
+(ref/units)= //TODO William This seems to be sporadically used. Keep?
+### Commonly used units of measure and their abbreviated forms
-| Unit | Unit Symbol or Abbreviation |
+| Unit | Unit symbol or abbreviation |
| :--------------------- | :-------------------------- |
| **bits per second** | bps |
| **byte** | B |
@@ -23,48 +23,14 @@ For a list of the preferred style choices of terms commonly used in Agora techni
| **megabit** | Mbit |
| **megabyte** | MB |
| **megahertz** | MHz |
-| **minute** | min. |
+| **minute** | min |
| **second** | s |
-(ref/issues)=
-### Common phrasing issues
-
-| **Not Preferred** | **Preferred** |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Agora SDK… | The Agora SDK… |
-| at most | maximum |
-| audiences | audience (when referring to the role)audience member (when referring to individuals) |
-| call the \[methodname\] method to | call \[methodname\] to |
-| check whether the function is enabled or not | check whether the function is enabled |
-| choose either of the following three formats | choose one of the following formats |
-| for more information, refer to… | see… |
-| on Electron | in Electron (Electron is a framework) |
-| in various dimensions | across various dimensions |
-| introduces how to use | describes how to use |
-| in the team | on the team |
-| is released | was released |
-| issues fixed | fixed issues |
-| it indicates... | (delete "it indicates...") |
-| listen to callback events | listen for callback events |
-| on the user interface | in the user interface |
-| open the camera | turn the camera on |
-| pass in an object as an argument | pass an object as an argument |
-| reserved parameter | reserved for future use |
-| sample codes | sample code |
-| save the bandwidth | reduce the bandwidth |
-| secret | encryption password |
-| the attributes for a channel | the attributes of a channel |
-| the saving directory | the directory to save |
-| this method must be called | you must call this method |
-| this method only works when | this method works only if |
-| we recommend | Agora recommends |
-| WeChat Miniprogram, WeChat Mini Program | WeChat Mini-program |
-| web (when referring to the platform/World Wide Web) | Web |
-| webpage, Web page | web page |
+//TODO William I moved the phrases that made sense to the Word List; others were already covered under specific grammar rules.
### Commonly used acronyms
-Examples of commonly used acronyms that do not need to be spelled out, along with their expanded form and a description of their meaning for reference:
+The following are commonly used acronyms that do not need to be spelled out, along with their expanded forms and descriptions of their meaning for reference:
| **Acronym** | **Expanded Form** | **Description** |
| ----------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -73,44 +39,44 @@ Examples of commonly used acronyms that do not need to be spelled out, along wit
| 5G | Fifth Generation | A telecommunication standard. |
| API | Application Programming Interface | A computing interface to a software component or system. |
| AVI | Audio Video Interleave | A multimedia container format and file type. |
-| CDN | Content Delivery Network | The process of publishing streams into the Content Delivery Networkis called CDN live streaming. |
-| CSS | Cascading Style Sheets | Used to describing the presentation of a document written in a markup language like HTML. |
-| DLL | Dynamic Link Library | Contains a library of functions and other information that can be accessed by a Windows program. |
-| HTML | Hypertext Markup Language | The standard markup language for Web pages. |
-| JPG | Joint Photographic Experts Group | The name of the group that devised this commonly-used lossy compression format for digital images. Now used to refer to the file format rather than the group. |
+| CDN | Content Delivery Network | A distributed network of proxy servers and data centers. The process of publishing streams into a content delivery network is called "CDN live streaming." |
+| CSS | Cascading Style Sheets | Computer language used to format Web page layout. |
+| DLL | Dynamic Link Library | A library of functions and other information that can be accessed by a Windows program. |
+| HTML | Hypertext Markup Language | The standard markup language for web pages. |
+| JPG | Joint Photographic Experts Group | The name of the group that devised this commonly used, lossy compression format for digital images. Now used to refer to the file format rather than the group. |
| JSON | JavaScript Object Notation | A stateless data interchange format used primarly on the Web. |
| M3U8 | Moving Picture Experts Group Audio Layer 3 Uniform Resource Locator | A common computer file format used for creating a multimedia playlist. The "8" means that the file is encoded in UTF-8. |
| MP4 | MPEG-4 Part 14 | A digital multimedia container format most commonly used to store video and audio |
-| MPEG | Moving Picture Experts Group | The name of the group that devised this commonly-used compression format for audio and visual digital data. Now used to refer to the file format rather than the group. |
+| MPEG | Moving Picture Experts Group | The name of the group that devised this commonly used compression format for audio and visual digital data. Now used to refer to the file format rather than the group. |
| PNG | Portable Network Graphics | A compressed, lossless digital image file format. |
| RESTful API | Representational State Transfer + ful | A software architecture that defines a set of constraints used for creating Web services. |
-| RTC | Real-time Communication | Used to refer to any live telecommunications that occur without transmission delays. |
-| RTMP | Real-time Messaging Protocol | A TCP-based protocol which maintains persistent connections and allows low-latency communication |
+| RTC | Real-time Communication | Any live telecommunications that occur without transmission delays. |
+| RTMP | Real-time Messaging Protocol | A TCP-based protocol that maintains persistent connections and allows low-latency communication. |
| SDK | Software Development Kit | A collection of software development tools in one installable package. |
| TS | MPEG Transport Stream | A standard digital container format for transmission and storage of audio, video, and related metadata. |
| TURN | Traversal Using Relays around NAT | A protocol that assists in traversal of network address translators (NAT) or firewalls for multimedia applications. |
-| URL | Uniform Resource Locator | A reference to a web resource that specifies its location on a computer network, typically on the Web. |
-| Wi-Fi | Wireless Fidelity (unofficial) | A family of wireless networking technologies, commonly used for local area networking of devices and Internet access. |
-| XML | Extensible Markup Language | A metalanguage used to define their customized markup languages. |
+| URL | Uniform Resource Locator | A reference to a web resource that specifies its location on a computer network, typically a web page. |
+| Wi-Fi | Wireless Fidelity (unofficial) | A family of wireless networking technologies, commonly used for local area networking of devices and internet access. |
+| XML | Extensible Markup Language | A markup language that defines rules for encoding documents in a format that is both human- and machine-readable. |
-### Common issues when native-Chinese speakers write English content
+### Common issues when native-Chinese speakers write English content //TODO William I am tempted to move this to its own chapter (and perhaps expand it if necessary) since it doesn't fit with the two reference tables here (three if you put Product names back here, which I hope you agree is best).
-The worldwide language of programming is English, so it is essential for our writing to sound like a native-English writer wrote it.
+The worldwide language of programming is English, so it is essential for our writing to sound like a native English speaker wrote it.
-Here are some issues that native-Chinese speakers sometimes encounter when writing English content and how to overcome them:
+The following are some issues that native Chinese speakers sometimes encounter when writing English content and how to overcome them:
#### Omitting or inserting articles
-In Chinese, there is no need for articles (such as the equivalent for "a", "an", and "the") before nouns, so Chinese speakers often forget to add the appropriate article in English. In some cases, Chinese speakers overcompensate and add an article when it is not needed. While there is no foolproof way to solve this problem, try speaking the English phrase out loud. If it sounds odd to you, it probably is. When in doubt, talk to a colleague, or reach out to a native English speaker.
+In Chinese, there is no need for articles ("a," "an," and "the") before nouns, so Chinese speakers often forget to add the appropriate article in English. In some cases, Chinese speakers overcompensate and add an article when it is not needed. While there is no foolproof way to solve this problem, try speaking the English phrase out loud. If it sounds odd to you, it probably is. When in doubt, talk to a colleague, or reach out to a native English speaker. See [](language-and-grammar.md#articles-a-an-the).
#### Gender confusion
-There aren't separate gender pronouns (such as "he" and "she", "his" and "her") in Chinese. In most technical writing, you should not have to refer to a specific gender in most instances, so use the gender non-specific "they" instead of the awkward "his/her" or "he/she" constructions.
+Chinese does not have separate gender pronouns (such as "he" and "she", "his" and "her"). In most technical writing, however, you should avoid referring to a specific gender. When necessary, use the gender non-specific "they" instead. See [](language-and-grammar.md#second-person).
-#### Singular and plural Nouns and Uncountable Nouns
+#### Singular and plural nouns and uncountable nouns
-In Chinese, context distinguishes between singular and plural nouns. In English, plural nouns often end with an "s" (for example: singular "method", plural "methods"). But this is not the case for all English nouns, such as the "uncountable nouns," which are things that cannot be counted by numbers. Examples include "information," "equipment," "knowledge," "research," "safety," and "evidence." These words are already plural, so they need no *s* at the end.
+In Chinese, context distinguishes between singular and plural nouns. In English, plural nouns often end with an "s" (for example: singular "method," plural "methods"). But this is not the case for all English nouns, such as the "uncountable nouns," which are things that cannot be counted by numbers. Examples include "information," "equipment," "knowledge," "research," "safety," and "evidence." These words are already effectively plural, so they need no *s* at the end. See [](language-and-grammar.md#articles-a-an-the).
-#### Verb tense confusion
+#### Verb-tense confusion
-There is no such thing as verb conjugation to denote past, present, or future tenses in Chinese, as context provides the necessary cues. Write using active voice and present tense in English to minimize any difficulty in using other tenses.
+There is no such thing as verb conjugation to denote past, present, or future tenses in Chinese, as context provides the necessary cues. Write using the active voice and present tense in English to minimize any difficulty in using other tenses. See [](language-and-grammar.md#active-voice) and [](language-and-grammar.md#present-tense).