From 765cbeef495f2d1f914e84c7ae64c0dc8632c228 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sun, 16 Feb 2025 14:27:18 -0800
Subject: [PATCH] Enhance Plone documentation style guide (#1864)

- Clarify why we use one sentence per line
- Add links to Microsoft Style Guide for verb tense, usage, and examples.
- Add `.vscode/settings.json` reference and example file.
---
 docs/_static/settings.json                 |  5 +++++
 docs/contributing/documentation/authors.md | 24 ++++++++++++++++++----
 2 files changed, 25 insertions(+), 4 deletions(-)
 create mode 100644 docs/_static/settings.json

diff --git a/docs/_static/settings.json b/docs/_static/settings.json
new file mode 100644
index 000000000..a836b007c
--- /dev/null
+++ b/docs/_static/settings.json
@@ -0,0 +1,5 @@
+{
+  "[markdown]": {
+    "editor.formatOnSave": false
+  }
+}
diff --git a/docs/contributing/documentation/authors.md b/docs/contributing/documentation/authors.md
index 679dbf5ec..66b96a8c5 100644
--- a/docs/contributing/documentation/authors.md
+++ b/docs/contributing/documentation/authors.md
@@ -337,16 +337,32 @@ We follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/styl
 Key concepts from that guide include the following.
 
 -   Documentation should be informational, but friendly.
--   Address the reader by using "you" instead of "the user", or by using the collective "we" and "our".
+-   Address the reader by using "you" and "your" instead of "the user" or "the user's".
+-   When giving instructions, use the [imperative](https://learn.microsoft.com/en-us/style-guide/grammar/verbs#mood-of-verbs).
+-   Use the [active voice](https://learn.microsoft.com/en-us/style-guide/grammar/verbs#active-and-passive-voice) whenever possible, avoiding the passive voice.
 -   Headings should be "Sentence cased", not "Title Cased".
 
 The Plone Documentation Team adopted additional guidelines.
 
 -   Use one sentence per line.
     Keep sentences short and understandable.
-    This will greatly improve the editing and maintenance of your documentation.
--   Do not follow the PEP8 maximum line length standard.
-    Documentation is narrative text and images, not Python code.
+
+    Never break a single sentence across multiple lines.
+    Documentation is narrative text and images, not code.
+    Do not follow the PEP8 maximum line length standard.
+    Similarly, never use English semantic line breaks.
+    English semantic rules are difficult to understand and enforce.
+
+    Not following this guidance makes pull request reviews needlessly difficult, often resulting in noisy diffs.
+    The reviewer can't give targeted feedback for a single sentence when there are multiple sentences on one line.
+    When a single sentence is broken across multiple lines, the reviewer has to submit one suggestion per line.
+    Most reviewers won't do that, and instead make a comment instead of a suggestion.
+    This in turn deprives you of the easy option to commit the suggestion to the pull request by a single click of a button in the GitHub user interface.
+
+    Following this guidance will greatly improve the editing and maintenance of your documentation.
+
+-   Have the file [`.vscode/settings.json`](/_static/settings.json) in the root of your project to prevent VSCode from reformatting files with the `.md` extension. 
+
 -   Use dashes `-` in filenames and avoid underscores.
 -   Images should be no wider than 740 pixels to fit within the documentation's main view port.
     This avoids scaling and reducing legibility of images.