Applied first batch of enhancements for 6.0 #414
Conversation
julian-cable
changed the title
en-US/Grammar.xml
Outdated
|
|
||
| <!-- Added section about "either, or" --> | ||
| <formalpara id="either-or"> | ||
| <title>Either, Or</title> |
There was a problem hiding this comment.
I think we need to do a better job with our titles. This will obviously be an ongoing task, but we need to avoid one-word titles and super brief titles like this one.
en-US/Grammar.xml
Outdated
|
|
||
| <!-- Added section about "following" --> | ||
| <formalpara id="following-noun"> | ||
| <title>Following</title> |
There was a problem hiding this comment.
Another title to update.
en-US/Grammar.xml
Outdated
| <formalpara id="if-then"> | ||
| <title>If, Then</title> | ||
| <para> | ||
| Follow an "if" statement with a "then" statement. |
There was a problem hiding this comment.
I wouldn't make this a blanket rule. Maybe add "generally" or similar? (And review the title.)
en-US/Grammar.xml
Outdated
| Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward 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. | ||
| </para> | ||
| <para> | ||
| In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. |
There was a problem hiding this comment.
| In most cases, when giving instructions, use the imperative mood or use "you". In more general explanations, you can use "the user" or "new users". Do not use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. Do not use "it" to refer to a person. | |
| 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. Using "one" is far too formal. Do not use "it" to refer to a person. |
en-US/Language.xml
Outdated
| @@ -946,6 +946,86 @@ Numbers (move from N entry) --> | |||
| </para> | |||
| </section> | |||
|
|
|||
| <!-- Added section for "easy, simple" --> | |||
| <section id="easy"> | |||
| <title>Avoiding "Easy"</title> | |||
There was a problem hiding this comment.
Don't use punctuation or markup in titles. I also think that this is unsuitable as a section on its own, especially at this level. We need to take the design and layout of the book into account. This would possibly fit under "Avoiding Ambiguities".
There was a problem hiding this comment.
Moved and fixed
en-US/Language.xml
Outdated
| <entry> Mounting a device is relatively simple. </entry> | ||
| <entry> Identify the device for mounting, ensure that the mount point exists, and mount the device on the mount point. </entry> |
There was a problem hiding this comment.
I don't see statement #2 as an improvement of statement #1. I think you could improve #1 by saying "Mounting a file system is straightforward." Statement #2 is about how to mount a file system. NB: Any device that you want to mount must have a file system on it. You could perhaps read the man page or even talk to Phil about an example if you want to improve further.
There was a problem hiding this comment.
Reworked the example. The intent here is to avoid stating that the task is easy, and to focus instead on how to do it.
en-US/Grammar.xml
Outdated
| </tgroup> | ||
|
|
||
| </table> | ||
|
|
||
| <!-- Added section about use of relative pronoun "that" --> | ||
| <formalpara id="that"> | ||
| <title>"That" in Clauses</title> |
There was a problem hiding this comment.
Let's try to remove punctuation in titles as we go.
| <entry> Divide the storage devices into smaller chunks to create a partition. </entry> | ||
| <entry> To create a partition, divide the storage devices into smaller chunks. </entry> |
There was a problem hiding this comment.
This is not really an example of a condition. Conditions typically start with "if": "If X then Y." This example is reversing "Do X to achieve Y" to become "To achieve Y, do X."
I also think we need a better example. "Dividing storage devices into smaller chunks" could mean a variety of things, and not necessarily create partitions. Maybe have a look at https://docs.fedoraproject.org/en-US/quick-docs/creating-a-disk-partition-in-linux/
I think it'd be pretty easy to make up a "bad example" and then improve it using the commands and examples documented here.
There was a problem hiding this comment.
My intent here was something other than an "if ... then" construction. I've removed the entry for now, and will think further about what to do.
en-US/Language.xml
Outdated
| <entry> Remote users can connect to network resources simply by authenticating to their local machine. </entry> | ||
| <entry> Remote users can connect to network resources by authenticating to their local machine. </entry> |
There was a problem hiding this comment.
Opportunity for more examples here? Are there exceptions? ("Modern hard drives can be very large.")
There was a problem hiding this comment.
Added more examples. (I would be inclined not to provide an exception to allow "very"; I think that a better alternative could often be found, such as "Modern hard drives can be so large that ...".)
en-US/Translation.xml
Outdated
| @@ -180,6 +183,70 @@ | |||
| </tgroup> | |||
|
|
|||
| </table> | |||
| <para> | |||
| For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment is hard to translate into other languages. | |||
There was a problem hiding this comment.
| For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment is hard to translate into other languages. | |
| For a lead-in sentence that introduces a list, use a complete sentence. A lead-in that is a sentence fragment can be difficult to translate into other languages. |
en-US/Grammar.xml
Outdated
| <entry> Scale up by adding more resources, with more memory, CPU, disk space, or other resources. </entry> | ||
|
|
There was a problem hiding this comment.
I would have written "...resources, such as memory, CPUs, disk space, and so on." Memory is not countable, and neither is disk space, but CPU is a countable noun.
en-US/Grammar.xml
Outdated
| <!-- Added section about use of relative pronoun "that" --> | ||
| <formalpara id="that"> | ||
| <title>"That" in Clauses</title> | ||
| <title>That in Clauses</title> |
There was a problem hiding this comment.
Without putting too fine a point on it, this is not a very exciting title. "That in Clauses"? I suggest reading the section a couple of times and a better title will probably reveal itself.
en-US/Language.xml
Outdated
| <section id="redundant"> | ||
| <title>Avoiding Redundant Words</title> | ||
| <para> | ||
| Avoid redundant words, such as "actually", "just", "really", "simply" and "very". They are filler words that add no value to a sentence. |
There was a problem hiding this comment.
We need to qualify this. Yes, sometimes they are redundant. Sometimes they are not. It depends on how they are used. E.g.,
- "We are proud of our content, and with just cause."
- "Why do you want to do this?" "Just because."
en-US/Language.xml
Outdated
| @@ -986,6 +1030,56 @@ Numbers (move from N entry) --> | |||
| </listitem> | |||
|
|
|||
| </varlistentry> | |||
| <!-- Added entry for "easy, simple" --> | |||
| <varlistentry id="easy"> | |||
| <term> Avoiding "Easy" </term> | |||
There was a problem hiding this comment.
Again, I don't think this title suits the content, and we shouldn't be using punctuation in titles.
en-US/Language.xml
Outdated
| <entry> Kubernetes is an orchestration service that makes it easier to deploy, manage, and scale container-based applications across a cluster of container hosts. </entry> | ||
| <entry> | ||
| <para> | ||
| Option 1: Kubernetes is an orchestration service that deploys, manages, and scales container-based applications across a cluster of container hosts. | ||
| </para> | ||
| <para> | ||
| Option 2: Kubernetes is an orchestration service that makes it easier than manual container management to deploy, manage, and scale container-based applications across a cluster of container hosts. |
There was a problem hiding this comment.
Please talk to Fernando about this one.
There was a problem hiding this comment.
Updated following feedback from Fernando.
en-US/Grammar.xml
Outdated
| <section id="pronouns-gender-references"> | ||
| <title>Pronouns and Gender References</title> | ||
| <para> | ||
| Do not use gender-specific pronouns in documentation, except to refer to a specific named user, such as in a case study. It is far less awkward 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. |
There was a problem hiding this comment.
Instead of "It is far less awkward to read..." how about "It is easier to read..."
Please review these enhancements for the upcoming October Release 6.0 of the style guide, to add previously missing guidance from the snippets.