Update the section: 6.3. The Repeatability Test

[rclee33]

In section 6.3., there is phrasing inconsistent with our goals for inclusivity and diversity: “Cross-referencing is a good servant but a poor master. Content still rules!” and “It's not a crime.” These metaphors are also barriers for non-native speakers. I suggest removing these sentences (or adjusting them to phrasing that is neutral and inclusive).

In addition, I also suggest adding an additional rationale for repetition: to help people learn. I’ll include a suggested update as a comment.

I also have a soft suggestion to update the section title for clarity and concision. Perhaps something like “6.3. Repetition”.

[rclee33]

Suggested revision for 6.3.

⁠6.3. Repetition
Repetition is a useful tool for reinforcing new knowledge and skills, emphasizing important ideas, and providing readers with important information at their point of need.

Repeating necessary information also saves the reader time and effort. In some circumstances, such as when using online help, the reader is trying to answer an immediate question or solve a problem. In a safety situation, it’s important for the reader to find critical information quickly.

If the information is vital, and must appear in multiple places, then it must be repeated. Any vital information, which is not more than a couple of paragraphs (or half a page, or five rows of a table), can be repeated rather than be cross-referenced to.

[daobrien]

If you run Vale over the style guide you'll probably find a few issues, such as the use of master and slave.

You'll need to update your local vale.ini file for this to work.
For the moment, this means not using a symlink to the template file in the vale-styles repo.
We'll get to that when we have time.

Add the following stanza before the [*.adoc] stanza.
It could probably go anywhere, but that's where I have it:

[*.xml]
Transform = /usr/share/sgml/docbook/xsl-stylesheets-1.79.2/html/docbook.xsl
BasedOnStyles = rht,redhat,Microsoft
# We don't use the RHT spelling checker because the style guide has lots of examples of what not to do.
rht.spelling = NO
redhat.capitalization = NO

Beware: Vale has had lots of updates since it was last run on the style guide, and you'll see lots of issues.
I strongly recommend doing one file at a time to begin with, and probably just focus on errors, not warnings.

Let's know if you need help.

[julian-cable]

Adopting Rachel's rewording for this section (with a minor change to eliminate a contraction).