diff --git a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst index 3223e6f30e0..2e5e399f95b 100644 --- a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst +++ b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst @@ -41,6 +41,32 @@ Bad: Better: Extraction also requires large volumes of water. +.. _one_sentence_per_line: + +Use one sentence per line +------------------------- +Consider using a technique called *one sentence per line* when composing paragraphs, or use at least one line per sentence (following https://sembr.org/). +This technique allows you to format RST and Markdown source in a natural and semantic way that is easy to review and edit. + +Lines of text that occur next to each other are rendered as a paragraph so readers do not notice the line breaks between sentences. +To create a new paragraph, add an empty line between sentences. +You can still soft wrap lines of text when using one sentence per line. +The important thing is that each line starts at the left margin. + +Using one sentence per line reduces cognitive load and makes life much easier for people who review changes. +Diffs become much more straightforward and easier to parse. +For example, when multiple sentences are wrapped at a fixed column width, a change at the start of a paragraph causes the remaining lines in the paragraph to reposition. + +In addition to the advantages for version control, one sentence per line makes it easier to do the following: + +- Swap sentences around. +- Separate or join paragraphs. +- Comment individual sentences. +- Identify sentences that are too long or that vary widely in length. +- Spot redundant patterns in your writing. + +For an example of the one sentence per line in the Ansible documentation, take a look at the RST source under ``docs/docsite/rst/getting_started/``. + Avoid verbosity --------------- Write short, succinct sentences. Avoid terms like: diff --git a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst index 016de47e9d6..f9a873b4a73 100644 --- a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst +++ b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst @@ -196,6 +196,9 @@ Spacing after sentences ^^^^^^^^^^^^^^^^^^^^^^^ Use only a single space after a sentence. +.. note:: + One sentence per line is preferred to wrapping sentences over multiple lines. See :ref:`one_sentence_per_line`. + Time ^^^^ * Time of day is written as "4 p.m."