fdp-primer/writing-style: improve English, and use own guidance

1 files changed, 31 insertions, 35 deletions

diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
index 9752ae1554..a4d3755f5d 100644
--- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc
@@ -52,7 +52,8 @@ endif::[]
 
 Technical documentation can be improved by consistent use of several principles.
 Most of these can be classified into three goals: _be clear_, _be complete_, and _be concise_.
-These goals can conflict with each other. Good writing consists of a balance between them.
+These goals can conflict with each other.
+Good writing consists of a balance between them.
 
 [[writing-style-be-clear]]
 === Be Clear
@@ -79,8 +80,7 @@ A trivial example is better than no example.
 A good example is better yet.
 Do not give bad examples, identifiable by apologies or sentences like "but really it should never be done that way".
 Bad examples are worse than no examples.
-Give good examples, because _even when warned not to use the example as shown_,
-the reader will usually just use the example as shown.
+Give good examples, because _even when warned not to use the example as shown_, the reader will usually just use the example as shown.
 
 Avoid _weasel words_ like "should", "might", "try", or "could".
 These words imply that the speaker is unsure of the facts, and create doubt in the reader.
@@ -98,18 +98,14 @@ Put yourself in the reader's place, anticipate the questions they will ask, and
 [[writing-style-be-concise]]
 === Be Concise
 
-While features should be documented completely,
-sometimes there is so much information that the reader cannot easily find the specific detail needed.
+While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed.
 The balance between being complete and being concise is a challenge.
-One approach is to have an introduction,
-then a "quick start" section that describes the most common situation,
-followed by an in-depth reference section.
+One approach is to have an introduction, then a "quick start" section that describes the most common situation, followed by an in-depth reference section.
 
 [[writing-style-guidelines]]
 == Guidelines
 
-To promote consistency between the myriad authors of the FreeBSD documentation,
-some guidelines have been drawn up for authors to follow.
+To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow.
 
 Use American English Spelling::
 There are several variants of English, with different spellings for the same word.
@@ -118,9 +114,8 @@ Where spellings differ, use the American English variant.
 +
 [NOTE]
 ====
-The use of British English may be accepted in the case of a contributed article,
-however the spelling must be consistent within the whole document.
-The other documents such as books, web site, manual pages, etc. will have to use American English.
+The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document.
+The other documents such as books, web site, manual pages, etc. must use American English.
 ====
 
 Do not use contractions::
@@ -165,7 +160,7 @@ Wrong: See `man csh` for more information.
 +
 Right: See man:csh[1].
 
-For more information about writing style, see http://www.bartleby.com/141/[Elements of Style], by William Strunk.
+For more information about writing style, see http://www.bartleby.com/141/[Elements of Style] by William Strunk.
 
 [[writing-style-guide]]
 == Style Guide
@@ -258,9 +253,9 @@ If a character is not on this list, ask about it on the {freebsd-doc}.
 
 To maintain clarity and consistency across all documentation and website pages, link:https://vale.sh[Vale] styles have been introduced in the documentation tree.
 link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios.
-At this moment link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipeline and integrated into editor of choice.
+Currently link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipelines, and integrated into an editor of choice.
 
-The following table describes the current rule names and respective severity.
+The following table describes the current rule names and their respective severity.
 
 [.informaltable]
 [cols="1,1", frame="none", options="header"]
@@ -303,32 +298,33 @@ The following table describes the current rule names and respective severity.
 [[writing-style-linting-vale-rules]]
 === Current Vale Rules
 
-. BrandTerms: Like The FreeBSD Project every major vendors and Companies have specific rules on writing their Brand Name. According to the Copyright rules of The FreeBSD Foundation *freebsd* should be written as *FreeBSD*.
-Similar to that care should be taken to be respective to other's brand value and write PostgreSQL, Node.js, Let's Encrypt etc.
+. BrandTerms: According to the copyright rules of The FreeBSD Foundation, *freebsd* should be written as *FreeBSD*.
+Similarly, every major vendor and company has specific rules on writing their brand names and trademarks.
+Care should be taken to be respectful to the brand value others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc.
 Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/BrandTerms.yml# in the `doc` repository.
 
 . Contractions: Contracted words should not be used. This rule avoids all contractions and suggests full words.
 
-. Hang: `Hang` is often used to convey the meaning that the application has stopped responding.
+. Hang: `Hang` is often used to mean that the application has stopped responding.
 This rule proposes better wording.
 
-. Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again.
+. Repetition: Some words are often typed twice when leaving the keyboard and rejoining the work again.
 This rule finds repeated words and warns the users.
 
-. Weasel: This rule handles avoiding weasel words.
-The uses of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning on.
-In case a frequently used word is marked as weasel word it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml# in the `doc` repository.
+. Weasel: This rule is aimed at avoiding weasel words.
+The concept of weasel words is controversial so at the moment the list of words are being evaluated and the severity level is marked as warning only.
+If a frequently used word is marked as a weasel word it should be removed from [.filename]#.vale/styles/FreeBSD/Weasel.yml# in the `doc` repository.
 
-. ConsciousLanguage: This rule proposes uses of conscious languages like avoiding the words white/black/master/slave.
+. ConsciousLanguage: This rule proposes uses of conscious language, for example avoiding the words white/black/master/slave.
 
-. EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation.
+. EOLSpacing: In most of the documents EOL spacing is present which is not wanted.
 
-. Hyphens: Often adverbs ending with 'ly' are being added with a hyphen which is wrong.
+. Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong.
 
-. Spacing: Often double spaces are hard to catch on plain eye which is addressed here.
+. Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here.
 
-. Spelling: At the moment there is a mix of en_US and en_UK spellings in the documentation and website.
-A custom dictionary from link:https://wordlist.aspell.net[Aspell] has been added which uses strictly en_US and do not accept the en_UK variant of any words.
+. Spelling: At the moment there is a mix of en_US and en_GB spellings in the documentation and website.
+A custom dictionary from link:https://wordlist.aspell.net[Aspell] has been added which uses strictly en_US and does not accept the en_GB variant of any words.
 It has also an exception list to ignore the FreeBSD specific terms.
 At the moment the list is a basic one with minimal words just as a proof of concept but if any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/FreeBSD/spelling-exceptions.txt# in the `doc` repository.
 
@@ -337,7 +333,7 @@ More rules will be introduced in the upcoming days when and where required.
 [[writing-style-using-vale]]
 === Using Vale
 
-link:https://vale.sh[Vale] can be used from command line and from within editor or IDE.
+link:https://vale.sh[Vale] can be used from the command line and from within an editor or IDE.
 package:textproc/vale[] can be installed as following:
 
 [source, shell]
@@ -346,9 +342,9 @@ $ pkg install vale
 ....
 
 [[writing-style-using-vale-commandline]]
-==== Using Vale in command line
+==== Using Vale on the command line
 
-Considering the fact that `doc` repository was cloned into [.filename]#~/doc# the following commands are required to run:
+Assuming that the `doc` repository was cloned into [.filename]#~/doc# the following commands are required to run:
 
 [source, shell]
 ....
@@ -359,12 +355,12 @@ Considering the fact that `doc` repository was cloned into [.filename]#~/doc# th
 [NOTE]
 ======
 link:https://vale.sh[Vale] is a CPU and memory intensive program due to the nature of the application and can take a while to show any output on the screen.
-Better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the CI pipeline.
+A better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the CI pipeline.
 ======
 
 [[writing-style-using-vale-editors]]
 ==== Using Vale in editors
 
 link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[].
-At the moment the necessary configurations for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim].
-Necessary configurations for package:editors/emacs[] is being worked on.
+At the moment the necessary configuration for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim].
+A configuration for package:editors/emacs[] is being worked on.