SUSE/doc-styleguide

Quotation marks, tags and punctuation

dariavladykina opened this issue · 4 comments

dariavladykina commented

This is a spinoff of the discussion in #223 - need to investigate the use of quote tags and quotation marks in our documentation.
Also, need to add guidance to use literal tags instead of quote here.

dariavladykina commented

The current guidance is "Use quotations to quote from sources, such as books. In all other cases, do not use quotation marks."

Other cases when they can also be used, as I see it, are :

  1. Titles = for more information, see Section 8.2, “Using ITS tags”
  2. To call attention to new words or phrases = "&systemd; introduces a new concept by using so-called "target units"
  3. To use them in a non-standard way = "packages can get in an "orphaned" state"
  4. To refer to a word or term itself = "The word "processor" came into use around 1910"
  • 👍1
dariavladykina commented

The Committee agreed to use emphasis for cases 2, 3, 4

dariavladykina commented

The Committee agreed on adding the guidance to avoid using single quotation marks.

dariavladykina commented

Closing this as it was merged.