From 1de7eecf9379e1a24716f1a00ae270a6f1a60ad1 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 00:15:33 +1000 Subject: [PATCH 1/3] Ongoing updates for #456 --- en-US/D.xml | 8 +++-- en-US/E.xml | 7 ++-- en-US/Easily_Confused_Words.xml | 9 +++-- en-US/F.xml | 19 ++++++++--- en-US/Grammar.xml | 60 +++++++++++++++++++++++---------- en-US/H.xml | 40 ++++++++-------------- 6 files changed, 86 insertions(+), 57 deletions(-) diff --git a/en-US/D.xml b/en-US/D.xml index e927504..8e8f0b3 100644 --- a/en-US/D.xml +++ b/en-US/D.xml @@ -142,7 +142,6 @@ - desire @@ -210,7 +209,12 @@ digital transformation - Avoid this phrase. It is vague and could mean use of digital technology to do something faster, to do something differently, or to do a completely new thing. The word "transform" implies a process with a beginning and an end. Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. Describe, rather than label. + Avoid this phrase. + It is vague and could mean use of digital technology to do something faster, to do something differently, or to do something new. + The word "transform" implies a process with a beginning and an end. + Some people use the phrase "digital leadership" to describe the ongoing adoption of digital technologies to advance their organization. + If you must discuss the concepts of digital transformation or digital leadership, briefly define what you mean on the first occurrence. + Describe, rather than label. diff --git a/en-US/E.xml b/en-US/E.xml index b76ba72..343e765 100644 --- a/en-US/E.xml +++ b/en-US/E.xml @@ -12,8 +12,6 @@ Refer to the primary reference for the type of copy you are creating, either AP or IBM. - - @@ -31,7 +29,8 @@ earlier - Use to refer to earlier releases of products. Do not use "older" or related terms. See also . + Use to refer to earlier releases of products. Do not use "older" or related terms. + See also . @@ -120,7 +119,7 @@ Ethernet - n. Uppercase "E" at all times. + n. Always capitalize as shown. diff --git a/en-US/Easily_Confused_Words.xml b/en-US/Easily_Confused_Words.xml index ef02831..4c464ff 100644 --- a/en-US/Easily_Confused_Words.xml +++ b/en-US/Easily_Confused_Words.xml @@ -33,13 +33,16 @@ effect - n. Refers to the result of some action. For example, "the team members discussed the effect of the new policy on their working conditions." + n. Refers to the result of some action. + For example, "the team members discussed the effect of the new policy on their working conditions." - v. Means to produce a result, or to cause something to happen. For example, "the CEO claimed that the new policy would effect a positive economic outcome." + v. Means to produce a result, or to cause something to happen. + For example, "the CEO claimed that the new policy would effect a positive economic outcome." - The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer. For example, "the CEO claimed that the new policy would produce a positive economic outcome." + The use of "effect" as a verb is less common than the use of "affect", and there are usually alternatives that are clearer. + For example, "the CEO claimed that the new policy would produce a positive economic outcome." diff --git a/en-US/F.xml b/en-US/F.xml index 9636404..81324ec 100644 --- a/en-US/F.xml +++ b/en-US/F.xml @@ -252,15 +252,20 @@ FQDN - A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated by using the dot or period character (.) as a separator between labels.https://en.wikipedia.org/wiki/Fully_qualified_domain_name + A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). + The domain labels are concatenated by using the dot or period character (.) as a separator between labels. + + + https://en.wikipedia.org/wiki/Fully_qualified_domain_name + + - For example, www.redhat.com is a fully qualified domain name, where www is the host, redhat is the second-level domain, and com is the top-level domain. + For example, www.redhat.com is a fully qualified domain name, where "www" is the host, "redhat" is the second-level domain, and "com" is the top-level domain. - An FQDN always starts with a hostname and continues all the way up to the top-level domain name; consequently www.parc.xerox.com is also an FQDN. + An FQDN always starts with a hostname and continues all the way up to the top-level domain name; consequently "www.parc.xerox.com" is also an FQDN. - @@ -269,7 +274,11 @@ frictionless - Avoid. This term is (a) jargon and (b) inaccurate. Nothing is ever really frictionless. Instead, talk about actual improvement in speed or time. See also . + Avoid. + This term is both jargon and inaccurate. + Nothing is ever really frictionless. + Instead, talk about actual improvement in speed or time. + See also . diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml index 2eb37eb..4457d31 100644 --- a/en-US/Grammar.xml +++ b/en-US/Grammar.xml @@ -203,7 +203,7 @@ - The jewel case, which once held the CD, was broken recently. + The jewel case, which previously held the CD, was broken recently. @@ -299,7 +299,10 @@ Sentence Length - Try not to pack too much information into one sentence. In technical documentation, try not to exceed 30 words in a sentence. Keep it short. The following sentence is a bad writing example: + Try not to pack too much information into one sentence. + In technical documentation, try not to exceed 30 words in a sentence. + Keep it short. + The following sentence is a bad writing example: @@ -328,13 +331,15 @@ - Separate independent clauses with a period. Doing so will form two sentences out of one. + Separate independent clauses with a period. + This creates two sentences from one. - Use semicolons to form a compound sentence. Think of a semicolon as an extended breather; it is longer than a comma. + Use semicolons to form a compound sentence. + Think of a semicolon as an extended breather; it is longer than a comma. @@ -390,13 +395,17 @@ Sentence Fragments - A sentence fragment is an incomplete sentence. For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. At least, before its time." the second of the two sentences is a fragment. Repair sentence fragments by making them complete sentences. + A sentence fragment is an incomplete sentence. + For example, "Red Hat releases no upgrade before its time." is a complete sentence, whereas in "We will release no upgrade. + At least, before its time." the second of the two sentences is a fragment. + Repair sentence fragments by making them complete sentences. - Read your sentences aloud, as if each sentence were the *only* sentence on a piece of paper. If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. + Read your sentences aloud, as if each sentence were the *only* sentence on paper. + If you hear a sentence that does not make any sense by itself, then it is probably a sentence fragment. @@ -423,7 +432,7 @@ Click button to start. - Click Initiate to start the process. + Click Start to start the process. @@ -717,8 +726,8 @@ - A site can use these to self-allocate a private routable IP address space inside the organization. - A site can use these unique local addresses to self-allocate a private routable IP address space inside the organization. + A site can use these to self-assign a private routable IP address space inside the organization. + A site can use these unique local addresses to self-assign a private routable IP address space inside the organization. @@ -773,7 +782,8 @@ Word Order - When two or more correct arrangements are possible, choose the order that will create the least ambiguity. Generally, this is the standard subject-verb-object, with modifiers before or immediately following what they modify. + When two or more correct arrangements are possible, choose the order that creates the least ambiguity. + Generally, this is the standard subject-verb-object sequence, with modifiers before or immediately following what they modify. @@ -814,7 +824,11 @@ Split contractions and abbreviations into separate paragraphs. -->
Contractions and Abbreviations - Do not use contractions in Red Hat documents. For example, do not use "can't", "don't", "won't", and similar examples. Write out the words in full. Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. They can also cause problems for translation. + Do not use contractions in Red Hat documents. + For example, do not use can't, "don't", "won't", and similar examples. + Write out the words in full. + Contractions are a mark of informal writing, and should be avoided when writing technical documentation or other more formal types of manuals. + They can also cause problems for translation. @@ -826,7 +840,10 @@ Split contractions and abbreviations into separate paragraphs. -->
Hyphenation - There are no hard and fast rules for hyphenation. In general, do not hyphenate unless required for clarity, or our other references declare that hyphens are required. The following is general guidance; if you are unsure about whether or not to hyphenate, ask your peers. See also the "Hyphens" topic in the IBM Style Guide. + No hard and fast rules exist for hyphenation. + In general, do not hyphenate unless required for clarity, or your other references declare that hyphens are required. + The following is general guidance; if you are unsure about whether to hyphenate, ask your peers. + See also the "Hyphens" topic in the IBM Style Guide. @@ -893,13 +910,19 @@ Split contractions and abbreviations into separate paragraphs. -->
Pronouns and Gender References - Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". It is acceptable to use "they" to refer to one person, with a plural verb. + Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. + It is easier to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers". + It is acceptable to use "they" to refer to one person, with a plural verb. - In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "users" or "new users". Do not use "one" in place of "you" when writing technical documentation, because it is too formal. Do not use "it" to refer to a person. + Usually, when giving instructions, use the imperative mood or use "you". + In more general explanations, you can use "users" or "new users". + Do not use "one" in place of "you" when writing technical documentation, because it is too formal. + Do not use "it" to refer to a person. - Avoid first person "I, we, our". Use second person "you" whenever possible. + Avoid first person "I, we, our". + Use second person "you" whenever possible. If referring to what Red Hat does, use "Red Hat" followed by a singular verb. @@ -945,11 +968,14 @@ Split contractions and abbreviations into separate paragraphs. -->
Tense - Avoid future tense (or using the term "will") whenever possible. For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. + Avoid future tense (or using the term "will") whenever possible. + For example, future tense ("The window will open ...") does not read as well as the present tense ("The window opens ..."). + Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system. - Use simple present tense as much as possible. It avoids problems with consequences and time-related communications, and is the easiest tense for translation. + Use simple present tense as much as possible. + It avoids problems with consequences and time-related communications, and is the easiest tense for translation. Report an issue diff --git a/en-US/H.xml b/en-US/H.xml index dea3153..5f87a4c 100644 --- a/en-US/H.xml +++ b/en-US/H.xml @@ -57,41 +57,26 @@ he/she - Do not use. Reword to avoid. In most cases, "they" is acceptable as a singular pronoun. + Do not use. + Usually, "they" is acceptable as a singular pronoun. - health check - n. Two words. This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. + n. Two words. + This is a change from the previous style standard (one word) to take advantage of the better search ranking of the two-word variation, and is used in product names that are similar to competitive offerings in the same space. This term is only capitalized when part of a product name, for example: - Red Hat Enterprise Linux Server Health Check - - - - - - JBoss Middleware Health Check + Red Hat Enterprise Linux Server Health Check @@ -100,7 +85,8 @@ - Do not capitalize when referring to those services in a general way. For example: "A health check ensures that your systems perform at their best." + Do not capitalize when referring to those services in a general way. + For example: "A health check ensures that your systems perform at their best." @@ -131,12 +117,13 @@ high-availability, high availability - adj. Hyphenate, except as part of a product name. For example, "high-availability cluster". - + adj. Hyphenate, except as part of a product name. + For example, "high-availability cluster". - n. Two words. For example, "Support is available 24x7 to help maintain high availability." + n. Two words. + For example, "Support is available 24x7 to help maintain high availability." @@ -156,7 +143,8 @@ home page - n. Two words. Capitalize the "H" at the beginning of a sentence. If part of a proper noun, capitalize accordingly. + n. Two words. + Capitalize the "H" at the beginning of a sentence or if part of a proper noun. @@ -176,7 +164,7 @@ hostname - n. One word in most cases. + n. Usually one word. Capitalize the "H" at the beginning of a sentence. See the IBM Style Guide for more information. From 70453b700532987e2c985a4c80222f888967990b Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 18:27:58 +1000 Subject: [PATCH 2/3] Closes #456 Part 2 of running Vale over the style guide. I also addressed a few other issues along the way, such as one sentence per line and removing old comments. Language.xml in particular contains lots of examples of what not to do, so it produces lots of noise in Vale. --- en-US/I.xml | 116 +++++++++++++++++++++++------------------- en-US/K.xml | 13 +++-- en-US/L.xml | 12 +++-- en-US/Language.xml | 123 +++++++++++++++++++++++++++++++-------------- 4 files changed, 167 insertions(+), 97 deletions(-) diff --git a/en-US/I.xml b/en-US/I.xml index 1408dac..541daeb 100644 --- a/en-US/I.xml +++ b/en-US/I.xml @@ -36,28 +36,16 @@ - IBM Z - IBM Z is a family name used by IBM for all of its mainframe computers from the Z900 on. In 2017, the official family was changed to IBM Z from IBM z Systems. + IBM Z is a family name used by IBM for all its mainframe computers from the Z900 on. + In 2017, the official family was changed to IBM Z from IBM z Systems. - i.e. @@ -80,12 +68,13 @@ - indexes - Correct. This is the correct plural form for US English spelling. Do not use "indices". + Correct. + This is the correct plural form for US English spelling. + Do not use "indices". @@ -96,7 +85,10 @@ InfiniBand - InfiniBand is a switched fabric network topology that is used in high-performance computing. The term is both a service mark and a trademark of the InfiniBand Trade Association. Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. + InfiniBand is a switched fabric network topology that is used in high-performance computing. + The term is both a service mark and a trademark of the InfiniBand Trade Association. + Their rules for using the mark are standard ones: append the ™ symbol the first time that it is used and respect the capitalization (including the inter-capped "B") from then on. + In ASCII-only circumstances, the "(TM)" string is the acceptable alternative. "Open InfiniBand" is deprecated and should not be used. @@ -109,7 +101,8 @@ inline - adj. Always one word. Do not hyphenate. + adj. Always one word. + Do not hyphenate. @@ -119,7 +112,8 @@ insecure - adj. Correct. Do not use "nonsecure" or "non-secure". + adj. Correct. + Do not use "nonsecure" or "non-secure". @@ -129,7 +123,8 @@ installation program - n. Correct. Do not use "installer" unless it is a formal part of the product or technology. + n. Correct. + Do not use "installer" unless it is a formal part of the product or technology. @@ -139,12 +134,12 @@ Intel 64 - Correct. Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86", or other variations as the name of this architecture. + Correct. + Do not use "Hammer", "x86_64", "x86-64", "x64", "64-bit x86", or other variations as the name of this architecture. The correct term for Intel's implementation of this architecture is "Intel® 64". - - When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. + When discussing the architecture generally, reference both AMD64 and Intel 64 implementations specifically. See also . @@ -179,7 +174,8 @@ Intel Tolapai / Intel® EP80579 Integrated Processor - Do not use the code-name, "Tolapai". Use the official brand name "Intel® EP80579 Integrated Processor". + Do not use the code-name, "Tolapai". + Use the official brand name "Intel® EP80579 Integrated Processor". @@ -189,10 +185,15 @@ Intel Virtualization Technology (Intel VT) - Correct. The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). Subsequent uses can be abbreviated to "Intel Vi". + Correct. + The first and all prominent uses of the name should be fully spelled out, immediately followed by the initialism. + For example, "Intel Virtualization Technology (Intel VT) for Intel 64 or Itanium architecture (Intel Vi). + Subsequent uses can be abbreviated to "Intel Vi". - Always write the initialism in uppercase, accompanied by the "Intel" mark. Do not use "Vi" or "VT". Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)". + Always write the initialism in uppercase, accompanied by the "Intel" mark. + Do not use "Vi" or "VT". + Do not use the initialism in any prominent places, such as in titles or paragraph headings, and do not include any trademark symbols, such as ™ or "(TM)". @@ -213,7 +214,8 @@ interesting - Avoid this term, because it is a substitute for showing the reader why something is of interest. For example, instead of writing "It is interesting to note ...", consider using a "Note" admonition. + Avoid this term, because it is a substitute for showing the reader why something is of interest. + For example, instead of writing "It is interesting to note ...", consider using a "Note" admonition. @@ -233,7 +235,8 @@ Internet of Things (IoT) - Correct. Capitalize as shown; spell out on the first occurrence; and use the initialism thereafter. + Correct. + Capitalize as shown; spell out on the first occurrence, and use the initialism thereafter. The Internet of Things (IoT) refers to uniquely identifiable objects and their virtual representations in an internet-like structure. @@ -259,10 +262,17 @@ I/O - Correct. Stands for input/output (pronounced "eye-oh"). The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. Every transfer is an output from one device and an input into another. Devices such as keyboards and mice are input-only devices, while devices such as printers are output-only. A writable CD is both an input and an output device. + Correct. + Stands for input/output (pronounced "eye-oh"). + The term "I/O" is used to describe any program, operation, or device that transfers data to or from a computer and to or from a peripheral device. + Every transfer is an output from one device and an input into another. + Devices such as keyboards and mice are input-only devices; devices such as printers are output-only. + A writable CD is both an input and an output device. - The term "I/O" is a non-countable noun. Append "operations" to refer to multiple units of I/O. For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. + The term "I/O" is a non-countable noun. + Append "operations" to refer to multiple units of I/O. + For example: I/O operations could not be recovered in situations where I/O should have been temporarily queued, such as when paths were unavailable. @@ -272,7 +282,9 @@ IOPS - Correct. All caps. Stands for input/output operations per second. + Correct. + All caps. + Stands for input/output operations per second. @@ -282,7 +294,9 @@ IP - Correct. Stands for Internet Protocol. Capitalize both letters. + Correct. + Stands for Internet Protocol. + Capitalize both letters. @@ -292,7 +306,9 @@ IP Masquerade - A Linux networking function. IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. + A Linux networking function. + IP Masquerade, also called IPMASQ or MASQ, allows one or more computers in a network without assigned IP addresses to communicate with the internet by using the Linux server's assigned IP address. + The IPMASQ server acts as a gateway, and the other devices are invisible behind it, so to other machines on the internet the outgoing traffic appears to be coming from the IPMASQ server and not from the internal PCs. Because IPMASQ is a generic technology, the server can be connected to other computers through LAN technologies such as Ethernet, Token-Ring, and FDDI, as well as dial-up connections such as PPP or SLIP. @@ -305,7 +321,9 @@ IPsec - IPsec stands for Internet Protocol security. According to its RFC, IPsec should be used. Do not use "IPSec". + IPsec stands for Internet Protocol security. + According to its RFC, IPsec should be used. + Do not use "IPSec". @@ -315,7 +333,9 @@ IP switching - A type of IP routing that Ipsilon Networks, Inc. developed. Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. This type of IP routing appears to be considerably faster than older router techniques. + A type of IP routing that Ipsilon Networks, Inc. developed. + Unlike conventional routers, IP switching routers use ATM hardware to speed packets through networks. + This type of IP routing appears to be considerably faster than previous router techniques. @@ -345,16 +365,20 @@ Itanium - A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. + A member of Intel's Merced family of processors, Itanium is a 64-bit RISC microprocessor. + Based on the EPIC (Explicitly Parallel Instruction Computing) design philosophy, which states that the compiler should decide which instructions should be executed together, Itanium has the highest FPU power available. - In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. In 32-bit mode, it is much slower. Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. + In 64-bit mode, Itanium can calculate two bundles of a maximum of three instructions at a time. + In 32-bit mode, it is much slower. + Decoders must first translate 32-bit instruction sets into 64-bit instruction sets, which results in extra-clock cycle use. Itanium's primary use is driving large applications that require more than 4 GB of memory, such as databases, ERP, and future internet applications. - Do not use the term "IA64". It can be used in file names because they are not printed in the content. + Do not use the term "IA64". + It can be used in file names because they are not printed in the content. @@ -364,26 +388,14 @@ Itanium 2 - Itanium 2 is correct. Do not use "Itanium2" and always use a non-breaking space between "Itanium" and "2". - - - - - - - diff --git a/en-US/K.xml b/en-US/K.xml index dcad72e..b6d9127 100644 --- a/en-US/K.xml +++ b/en-US/K.xml @@ -43,7 +43,10 @@ kernel - The central module of an operating system. It is the part of the operating system that loads first, and it remains in main memory. Because it stays in memory, it is important for the kernel to be as small as possible while still providing all the essential services that other parts of the operating system and applications require. Typically, the kernel is responsible for memory management, process and task management, and disk management. + The central module of an operating system. + It is the part of the operating system that loads first, and it remains in main memory. + Because it stays in memory, it is important for the kernel to be as small as possible but still provide all the essential services that other parts of the operating system and applications require. + Typically, the kernel is responsible for memory management, process and task management, and disk management. @@ -63,7 +66,8 @@ kernel panic - Correct. Numerous circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. + Correct. + Many different circumstances might cause a kernel panic, but unlike a kernel oops, when confronted with a kernel panic the operating system shuts down to prevent the possibility of further damage or security breaches. @@ -148,7 +152,10 @@ kill - If terminating a UNIX process, use "kill". For example, to terminate the process, type kill <PID>. If terminating a Windows process, use "terminate". For example, "To terminate the process, press Q." + If terminating a UNIX process, use "kill". + For example, to terminate the process, type kill <PID>. + If terminating a Windows process, use "terminate". + For example, "To terminate the process, press Q." diff --git a/en-US/L.xml b/en-US/L.xml index 07c969b..b37b011 100644 --- a/en-US/L.xml +++ b/en-US/L.xml @@ -160,7 +160,11 @@ load balancing - Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. Busy websites typically employ two or more web servers in a load balancing scheme. If one server starts to get swamped, requests are forwarded to another server with more capacity. Load balancing can also refer to the communications channels themselves. + Distributing processing and communications activity evenly across a computer network so that no single device is overwhelmed. + Load balancing is especially important for networks where it is difficult to predict the number of requests that are issued to a server. + Busy websites typically use two or more web servers in a load balancing scheme. + If one server starts to get swamped, requests are forwarded to another server with more capacity. + Load balancing can also refer to the communications channels themselves. @@ -170,12 +174,14 @@ logical topology - Also called signal topology. Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. + Also called signal topology. + Every LAN has a topology, which refers to the way that the devices on a network are arranged and how they communicate with each other. + The physical topology is the way that the workstations are connected to the network through the cables that transmit data: the physical structure of the network. + The logical topology, in contrast, is the way that the signals act on the network media, or the way that the data passes through the network from one device to the next without regard to the physical interconnection of the devices. - login, log in diff --git a/en-US/Language.xml b/en-US/Language.xml index e9d6273..5b612b3 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -126,7 +126,9 @@ at this point in time - Do not use. In most cases, use "now". In some cases it is acceptable to use "at this point", for example, when you have reached a specific point in a procedure. + Do not use. + In most cases, use "now". + In some cases it is acceptable to use "at this point", for example, when you have reached a specific point in a procedure. @@ -136,7 +138,9 @@ automagic - Also, automagical. Both terms are slang. Do not use. + Also, automagical. + Both terms are slang. + Do not use. @@ -146,7 +150,11 @@ best-of-breed - Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. + Jargon. + Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". + Other alternatives include best, foremost, most advanced, and optimum. + The category is usually implied. + Be wary of using superlatives without data to back up any claims. @@ -162,16 +170,17 @@ - + bottom line @@ -187,7 +196,8 @@ bucketize - Not a word. Try "categorize" or "organize into logical groups". + Not a word. + Try "categorize" or "organize into logical groups". @@ -207,7 +217,9 @@ check this site - Understood to mean "have a look at this website". The preferred phraseology is "See www.somewhere.com for more information." It is better to avoid "check" because it has so many meanings. + Understood to mean "have a look at this website". + The preferred phraseology is "See www.somewhere.com for more information." + It is better to avoid "check" because it has so many meanings. @@ -218,7 +230,8 @@ core competency - Jargon, cold and impersonal. Better choices include "specialization", "skill", "strength", "expertise", and so on. The De-Jargonator says: "'Competent' means 'adequate but not exceptional.' Why would you describe what you do best as 'competence'? Try instead: What your organization does best; competitive advantage; special or unique expertise or ability; specialty." + Jargon, cold and impersonal. + Better choices include "specialization", "skill", "strength", "expertise", and so on. @@ -238,7 +251,9 @@ dig deeper, delve deeper - "Visit the following web link to dig deeper into [subject] ...". Using "dig deeper" may translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]." + "Visit the following web link to dig deeper into [subject] ...". + Using "dig deeper" may translate awkwardly. + Consider rewording: "For detailed information regarding [subject], see [link]." @@ -258,7 +273,8 @@ double-edged sword, double-bladed sword - If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. + If something is described as a double-edged sword, it indicates that it has two opposing behaviors or consequences. + Instead, state that it can have unexpected consequences, or that the positive result might be offset by the negative result. @@ -268,7 +284,9 @@ eat your own dogfood - Developer-speak. It means to use your own products. You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. + Jargon. + It means to use your own products. + You can get a detailed description at http://en.wikipedia.org/wiki/Eat_one%27s_own_dog_food. @@ -278,7 +296,7 @@ enterprise-ready - Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you're calling this out as a key selling point. + Although Red Hat used to use this term to emphasize its products' enterprise readiness, it is not as necessary now, especially when talking about a product with "Enterprise" in its name, unless you are calling this out as a key selling point. @@ -288,7 +306,8 @@ exceed your expectations - Vague. Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." + Vague. + Clarify with specifics, for example, "The movie made more money on the opening weekend than anyone expected." instead of "The movie exceeded our expectations." @@ -309,7 +328,8 @@ flog a dead horse - Do not use. Explain exactly what you mean, such as "a waste of effort". + Do not use. + Explain exactly what you mean, such as "a waste of effort". @@ -319,7 +339,9 @@ fly by the seat of your pants - Generally understood to mean "reacting to events as they occur". Difficult to offer alternatives without context. + Slang. + Generally understood to mean "reacting to events as they occur". + Difficult to offer alternatives without context. @@ -483,7 +505,8 @@ kettle of fish - Commonly used in the expression "a different kettle of fish", meaning "that's a different matter (altogether)". Depending on the context, try to use "topic", "subject", "matter", or something similar. + Commonly used in the expression "a different kettle of fish", meaning "that is a different matter (altogether)". + Depending on the context, use "topic", "subject", "matter", or something similar. @@ -493,7 +516,8 @@ leverage - Avoid. Alternatives include "use" and "take advantage of". + Avoid. + Alternatives include "use" and "take advantage of". @@ -637,7 +661,8 @@ ready to rumble - "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start". + "Let's get ready to rumble!" is a trademarked catchphrase used to introduce televised boxing or wrestling events. + In US English slang, being "ready to rumble" means you are "ready to go ahead" or "ready to start". @@ -689,7 +714,9 @@ shy of - Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he didn't quite succeed. Also, to be "a few items shy of what's required" means to have fewer than the minimum required number. Avoid this terminology and use more easily understood terms; it will help translators and also those reading English documentation who are unfamiliar with such slang. + Apart from the "normal" meaning of shy, it is also found in such phrases as "he was just shy of the mark", meaning that he did not quite succeed. + Also, to be "a few items shy of what is required" means to have fewer than the minimum required number. + Avoid this terminology and use more easily understood terms; it helps translators and also those reading English documentation who are unfamiliar with such slang. @@ -773,7 +800,8 @@ under the covers - This refers to something being out of plain sight or not immediately obvious. For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you can't see or are not aware of, to make that action of command possible. + This refers to something being out of plain sight or not immediately obvious. + For example, you might only see the results of some action or command, but what happens "under the covers" is what is going on in the background, that you cannot see or are not aware of, to make that action of command possible. @@ -783,7 +811,9 @@ value-added - Jargon. Say "added value" or "valuable". Or be more specific, for example, "adds value by improving productivity". + Jargon. + Say "added value" or "valuable". + Or be more specific, for example, "adds value by improving productivity". @@ -839,11 +869,10 @@
-
Phrasal Verbs - Avoid using a two-word verb form (a phrasal verb) if a one-word equivalent exists. + Avoid using two-word verb forms (phrasal verbs) if a one-word equivalent exists. @@ -978,19 +1007,28 @@ Follow these guiding principles: - Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad, such as "whitelist" and "blacklist". Such usage reinforces a model that promotes racial bias. + Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad, such as "whitelist" and "blacklist". + Such usage reinforces a model that promotes racial bias. For alternatives, choose words that describe the action that is taken or the function that is performed, rather than a metaphor for that action or function, for example "allowlist" instead of "whitelist", or "blocklist" or "denylist" instead of "blacklist". - Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. + Do not use "master" when it is paired with "slave". + Such use diminishes the horror of the dehumanizing practice of slavery. + Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill. - Avoid gender bias. As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. Thus, instead of using "man hours", use "labor hours" or "person hours". Avoid binary gendered language, such as "he" or "she", except to refer to a specific named person. Do not use "he or she". Instead, use the ungendered "they" as the preferred pronoun. + Avoid gender bias. + As an example, do not assume that the subject of a sentence is male if the context might refer to any gender. + Thus, instead of using "man hours", use "labor hours" or "person hours". + Avoid binary gendered language, such as "he" or "she", except to refer to a specific named person. + Do not use "he or she". + Instead, use the ungendered "they" as the preferred pronoun. - Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. + Avoid neurodiversity bias. + For example, avoid the terms "sanity check" and "sanity test", and do not use "disabled" to refer to a person. Avoid superlatives in job titles and descriptions, especially problematic terms such as "guru", "ninja", "rockstar", or "evangelist". @@ -1000,11 +1038,11 @@ -
Avoiding Redundant Words - Avoid redundant words, such as "actually", "really", "simply" and "very". They are typically filler words that add no value to a sentence. + Avoid redundant words, such as "actually", "really", "simply", and "very". + They are typically filler words that add no value to a sentence. Redundant words might also occur where two words or phrases are used that mean approximately the same thing, such as "revert back" versus "revert", or that add nothing to the sentence, such as "located on" versus "on". @@ -1035,8 +1073,8 @@ - Restore the LUKS2 header to the encrypted volume located on the `/dev/sda1` partition. - Restore the LUKS2 header to the encrypted volume on the `/dev/sda1` partition. + Restore the LUKS2 header to the encrypted volume located on the /dev/sda1 partition. + Restore the LUKS2 header to the encrypted volume on the /dev/sda1 partition. @@ -1057,7 +1095,8 @@ Capitalizing Proper Nouns - In some cases it is not clear if a term refers to a concept or a proper noun or product name. By using the correct capitalization, you will help translators identify untranslatable proper nouns and Red Hat product names. + In some cases it is not clear if a term refers to a concept or a proper noun or product name. + By using the correct capitalization, you help translators identify untranslatable proper nouns and Red Hat product names.
@@ -1088,12 +1127,13 @@ - Avoid Stating that Something Is Easy - Avoid stating that a task is easy to do or that a product is easy to use. Avoid "friendly" and "user-friendly" and similar terms. Focus instead on how to accomplish a task or on relevant features of a product. + Avoid stating that a task is easy to do or that a product is easy to use. + Avoid "friendly" and "user-friendly" and similar terms. + Focus instead on how to perform a task or on relevant features of a product.
@@ -1135,7 +1175,10 @@ Homographic Verbs - The verb "may" might indicate possibility or grant permission. Similarly, "should" might imply a recommendation or express obligation or expectation. A sentence containing one of these verbs often has a double meaning. Avoid these types of words. + The verb "may" might indicate possibility or grant permission. + Similarly, "should" might imply a recommendation or express obligation or expectation. + A sentence containing one of these verbs often has a double meaning. + Avoid these types of words.
@@ -1190,7 +1233,7 @@ Homonymity - When a single term has multiple meanings, be explicit in order to differentiate between them. + When a single term has multiple meanings, be explicit to differentiate between them.
@@ -1408,7 +1451,9 @@ Synonymity - Sometimes multiple terms have a single meaning. If terms are used inconsistently, users (and translators) will assume they refer to different things. It is best to use a single term for a single concept throughout. + Sometimes multiple terms have a single meaning. + If terms are used inconsistently, users (and translators) might assume they refer to different things. + It is best to use a single term for a single concept throughout. For example, "Administration UI" and "Administration Console" could both be used to refer to a single application or to different applications. For this reason it is important that writers choose the most suitable term for each situation and use it consistently. @@ -1614,4 +1659,4 @@ - \ No newline at end of file + From 1e7ae192559f0f6e51ed57eb6321f78c085be624 Mon Sep 17 00:00:00 2001 From: daobrien Date: Thu, 2 Feb 2023 22:11:42 +1000 Subject: [PATCH 3/3] s/may/might/ per Julian's review. --- en-US/Language.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en-US/Language.xml b/en-US/Language.xml index 5b612b3..d0d2035 100644 --- a/en-US/Language.xml +++ b/en-US/Language.xml @@ -252,7 +252,7 @@ "Visit the following web link to dig deeper into [subject] ...". - Using "dig deeper" may translate awkwardly. + Using "dig deeper" might translate awkwardly. Consider rewording: "For detailed information regarding [subject], see [link]."