Skip to content

Add one sentence per line to the style guide #2470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: devel
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/docsite/rst/dev_guide/style_guide/basic_rules.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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."