Skip to content
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

Writing style: additions, improvements #248

Closed
wants to merge 9 commits into from
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ For more information about writing style, see http://www.bartleby.com/141/[Eleme
To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions.

[[one-sentence-per-line]]
== One sentence per line
=== One sentence per line

Use Semantic Line Breaks in the documentation, a technique called "one sentence per line".
The idea of this technique is to help the users to write and read documentation.
Expand All @@ -187,8 +187,34 @@ All human beings are born free and equal in dignity and rights.
They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
....

[[sentence-spacing]]
=== Spaces between sentences

There are two conventions.

*Generally*:

* one space.

This generalization includes monospaced representation of monospaced texts that do _not_ follow the two spaces convention.

Where a variable-width font will be used: the per-line convention, above, will usually negate the need to think about spacing.

If a multi-sentence list item does use a space between sentences (with the possibility of strictly replacing the space with a line break):

* consider edition, to have no more than one sentence per point
** do not assume that nesting of points is the solution
** instead, an adjacent bullet point might be promoted to a simple paragraph.

*Exceptionally*:

* two spaces in errata notices
* two spaces in security advisories
* two spaces in manual pages (in the `src` tree, for example)
* two spaces in other files that will normally be viewed with a monospaced font.
grahamperrin marked this conversation as resolved.
Show resolved Hide resolved

[[writing-style-acronyms]]
== Acronyms
=== Acronyms

Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (NTP)".
After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term.
Expand Down