redhat-documentation / vale-at-red-hat Goto Github PK

https://redhat-documentation.github.io/supplementary-style-guide/#_a

air gap (noun)
Description: "Air gap" is the physical segregation and isolation of a system as a security measure.

Use it: yes

Incorrect forms: air wall

See also:

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Contractions

Avoid contractions in product documentation to leave no ambiguity and to make it easier for translation and international audiences.

If you are writing quick start or other content that uses a more informal conversational style (fairly conversational or more conversational), you may use contractions. In this case, follow the guidance in the IBM Style Guide on using contractions.

See: https://redhat-documentation.github.io/supplementary-style-guide/#contractions

(Rather than current implementation that follows IBM style guide).

/scripts folder to include a modified version of https://github.com/aireilly/supplementary-style-guide/tree/master/vale_rules POC + unit tests. More details TBD :)

Implement https://redhat-documentation.github.io/supplementary-style-guide/#admonitions as a suggestion

message: Keep admonitions to a minimum
level: suggestion

when NOTE, IMPORTANT, WARNING, TIP is present

Souvik Sarkar 1 hour ago: If you place the .ini files within the project directory, then you might have to either add them as exceptions in .gitignore (needs buy in from the greater community of contributors), or manually stage the modified files every time you make changes and commit, instead of the usual git add .

This item is a more conceptual and a bit of an edge case: the current instructions for installing the Vale at Red Hat style bypass this issue altogether. However, we should probably discuss this as an alternative configuration scenario.

Is your feature request related to a problem? Please describe.

According to FAQs: CCS style guides and term conventions, "The Red Hat Technical Publications Writing Style Guide (stylepedia.net) is no longer being used in CCS. It is still in use outside CCS, but it is no longer official for our group."

HOWEVER, Ingrid Towey states that stylepedia is still used by some people upstream (we're not sure who) and a technical docs group under Sales.

• Who are these users?
• Do their tools and file formats support Vale style linter?
• Do they want or need a Vale style?
• Do we want this Vale style for Red Hat project to include non-CCS use cases?
• What is the priority of such a project?

Describe the solution you'd like

Depending on our conversations and the answers to the preceding questions, it might make sense to include stylepedia within the scope of this project. If so, we would create a stylepedia subdirectory in the Red Hat style and begin creating rules from it.

Describe alternatives you've considered

If the tools and file format of stylepedia users do not support Vale, they might consider using other style-checker tools such as Acrolink, Grammarly, and so on.

Additional context
Add any other context or screenshots about the feature request here.

Implement https://redhat-documentation.github.io/supplementary-style-guide/#lead-in-sentences
See: https://docs.errata.ai/vale/styles#sequence-v230

When writing prerequisites, be as clear and concise as possible. You can use the passive voice, if necessary, to achieve that end. See: https://redhat-documentation.github.io/supplementary-style-guide/#prerequisites

 12:62  error  Use 'bare-metal' rather than    RedHat.agnostic 
               'bare metal'.                                   

The SSG accepts it under certain circumstances:

https://redhat-documentation.github.io/supplementary-style-guide/#bare-metal-adj
https://redhat-documentation.github.io/supplementary-style-guide/#bare-metal-n

Should we rename .vale/styles/Vocab/Che to "Red-Hat" or instruct users to create a new directory for their product, such as .vale/styles/Vocab/Logging?

When I added a Logging directory and updated line 11 in .vale.ini like this:

Vocab = Che, Logging

...I got errors:

[rolfedh@fedora-desktop openshift-docs]$ vale modules/cluster-logging-kibana-*
E100 [vocab] Runtime error

Vocab 'Che, Logging' does not exist

Should we renaming Che to Red-Hat and instructing users to add their product names to .vale/styles/Vocab/Red-Hat/accept.txt?

Describe the bug
Vale reports issues with "as", as shown in the following output. However, those instances seem to be valid uses.
Review the IBM Style Guide and to refine the IBM.Usage rule to reduce false positives.

To Reproduce
Steps to reproduce the behavior:

1. Run

[rdlugyhe@rdlugyhe ~]$ cd studious-fortnight/
[rdlugyhe@rdlugyhe studious-fortnight]$ ls
_config.yml  README.md   troubleshooting-common-errors.md
LICENSE      red-hat.md  vale-at-red-hat-blog.md
[rdlugyhe@rdlugyhe studious-fortnight]$ vale *.md
...
3:81    suggestion  Verify your use of 'as' with    IBM.Usage        
                     the word usage guidelines.                       
 7:1     suggestion  Verify your use of 'As' with    IBM.Usage        
                     the word usage guidelines.                       
 7:41    suggestion  Verify your use of 'as' with    IBM.Usage        
                     the word usage guidelines. 

Expected behavior

Upon inspection, these seem to be valid uses of "as". I think I can refine the rule to identify undesireable uses of "as" == "because".

Screenshots

Most of these seem like valid usages to me.

Results for "as" in "studious-fortnight/*.md"

/home/rdlugyhe/studious-fortnight/README.md:
  3:  at Red Hat get up and running with Vale. It serves as the starting point for the Vale Community of Practice
  7:  As a technical writer, you can use Vale as a command-line tool to check your content files for style issues.
  7:  As a technical writer, you can use Vale as a command-line tool to check your content files for style issues.
  30:  As a technical writer at Red Hat, you can use this repo to help you get started with using Vale.
  78:  Review the output for `Vale.Spelling` errors for valid words, such as words that appear in the product.
  96:  * You can use a style as-is, or you customize the rules it contains to fit your needs.


/home/rdlugyhe/studious-fortnight/.vale/styles/IBM/README-proselint.md:
  12:  PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,


/home/rdlugyhe/studious-fortnight/.vale/styles/IBM/README-write-good.md:
  20:  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

For an easier onboarding on Fedora and RHEL, a vale and a vale-style-red-hat RPM package would be nice.

Even better is they are listed there: https://repology.org/project/vale/versions

Create a video for Using vale CLI on a local environment and add it to the page.

Consider hosting the video on asciinema.org.

Make sure we implement Supplementary Style Guide changes.

How to get best informed from a change in the Supplementary Style Guide repository?

Automatically update/recreate the rules?

https://redhat-documentation.github.io/supplementary-style-guide/#_a

agnostic (adjective)
Description: "Agnostic" denotes or relates to hardware or software that is compatible with many types of platforms or operating systems. For example, many common file formats (JPEG, MP3, and others) are platform agnostic. Use "neutral" instead.

Use it: no

Incorrect forms:

See also:

I should add a project plan to this repo, outlining the goals, deliverables, and tasks.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Define and create modular docs rules.
The test-adoc.sh script by @jhradilek is a good source of inspiration: https://github.com/jhradilek/check-links

In the RH SSG, "bare metal" is correct in the noun form, while "bare-metal" is correct when used as an adjective. Currently, the generated Vale rules bare-metal-n.yml and bare-metal-adj.yml offer conflicting advice.

https://redhat-documentation.github.io/supplementary-style-guide/#bare-metal-adj

https://redhat-documentation.github.io/supplementary-style-guide/#bare-metal-noun

Implement Conscious language rule.

• https://redhat-documentation.github.io/supplementary-style-guide/#conscious-language
• https://github.com/conscious-lang/conscious-lang-docs/blob/main/faq.md

AMD64 (noun)
Description: "AMD64" is the AMD implementation of a 64-bit version of the x86 architecture.

Use it: yes

Incorrect forms: Hammer, x86_64, x86-64, x64, 64-bit x86

See also:

NOTE
The AMD64 logo is trademarked; the term "AMD64" is not trademarked. For more information about AMD trademarks, see the AMD Trademark Information page.

For more information about Intel® trademarks, see the Trademark Information and Usage Guidelines for Customers, Licensees, and Other Third Parties pages.

https://redhat-documentation.github.io/supplementary-style-guide/#_a

https://github.com/marketplace/actions/vale-linter

Should we rename the Che style to "Red-Hat"?

Enable RestructuredText in Vale configuration.

Add the following to the .vale.ini file and test:

[*.rst]
BasedOnStyles = RedHat

Context: The Red Hat Supplementary Style Guide has specific rules for release notes. The user wants these rules to apply to release notes, but avoid false flags in general content.

Approach: While it might be possible to solve this problem using scoping, the OpenShift docs repo already has release notes in a separate folder from the main documentation. I will try to create a .vale.ini for the parent folder that ignores the ReleaseNotes.yml rules. The .vale.ini for the the release notes folder will include the ReleaseNotes.yml rules.

Finish creating feature requests for each word in https://redhat-documentation.github.io/supplementary-style-guide/#_a
Exclude words that already have feature requests.

Describe the bug

In the spirit of the table of common prefixes and examples of when to omit or use a hyphen on page 81 of IBM Style, 'multi-tenant' in project docs was changed to 'multitenant', which resulted in a Vale error.
The problem was successfully solved as described in the steps to reproduce.

To Reproduce
Steps to reproduce the behavior:

1. Add <encouraged_spelling> to accept.txt.
2. Add <discouraged_spelling> to reject.txt.

Expected behavior
No Vale error.

Desktop (please complete the following information):
RHEL 8 CSB

Vale version
2.10.3

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Implement https://redhat-documentation.github.io/supplementary-style-guide/#single-step-procedures
See: https://docs.errata.ai/vale/styles#sequence-v230

Souvik Sarkar 1 hour ago: It would be great if you include how to download and unpack the Vale tar file, and then place the appropriate .ini files for the Vale - Red Hat specific stuff in the project directory.

Good suggestion, Souvik:

• This video is only one in a planned series of videos on how to install, configure, and use Vale with the Red Hat style. My installation videos will cover the most common ways to install Vale, including the one you mention.

Create a container with the Vale CLI and the RedHat style enabled by default.

Host the container on Quay.

Ensure the container is refreshed after each release (aka. commit on main).

Investigate creating a proper RPM / dnf package, both for vale and the RedHat style.

Investigate how to publish teh RedHat style RPM: COPR?

Investigate how to publish the RPM packages upstream for vale: https://repology.org/project/vale/versions or https://github.com/errata-ai/vale/releases

Is your feature request related to a problem? Please describe.
Feature request, having version tags and releases will allow easier identification of issues and allow users to see what changed between releases.

Describe the solution you'd like
Add tags (v1) and create GitHub releases with versions.

Additional context
Having a version will allow me to track updates and in-turn update the rules in online web app.

Test and integrate modular docs rules created by @jhradilek: https://github.com/jhradilek/vale-modular-docs

Edit from @rohennes - we are working on https://github.com/rohennes/ocp-rules to meet the same ask, so using this issue as a tracker for the work on this repo

The cloud-n.yml and cloud-adj.yml are reporting errors for this legit product name:

Certified Cloud and Service Provider (CCSP)

Implement https://redhat-documentation.github.io/supplementary-style-guide/#text-entry

level: suggestion

alright (adjective)
Description: "Alright" is the colloquial form of "correct" or "as expected."

Use it: no

Incorrect forms:

See also:

https://redhat-documentation.github.io/supplementary-style-guide/#_a

The SSG has a number of word usage guidance items that includes parenthesis. Vale does not like parenthesis in search terms, and doesn't seem to be able to search for the escaped characters, for example \( or \).

Example rule red-hat-network-satellite-server.yml:

extends: substitution
message: "Use '%s' instead of '%s'."
link: https://redhat-documentation.github.io/supplementary-style-guide/#red-hat-network-satellite-server
ignorecase: true
level: error
action:
  name: replace
source: Red Hat
swap:
    Red Hat Satellite (Server) : Red Hat Network Satellite Server

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Implement redhat-documentation.github.io/supplementary-style-guide/#admonitions as an error

CAUTION is not fully supported by the Red Hat Customer Portal. Do not use this admonition type.

message: Use NOTE, IMPORTANT, WARNING or TIP admonition type rather than CAUTION
level: error

when CAUTION is present

Describe the bug
Running vale with a recent version of the Red Hat style generates the following error when it encounters "shell prompt" in the content.

 201:27   error  Use 'shell prompt' rather than  RedHat.shell-prompt 
                 'shell'.                                            
 201:267  error  Use 'shell prompt' rather than  RedHat.shell-prompt 
                 'shell'. 

It should not generate this error when the expected phrase is already present.

Describe the bug

IBM Style (p. 292):

Meanwhile:

To Reproduce
Steps to reproduce the behavior:

1. Add this word or expression:
2. Vale reports an illegitimate alert: error, warning, suggestion.

Expected behavior
A clear and concise description of what you expected to happen.

Additional context
Add any other context here.

Create a reference guide containing a page for each rule, that we could use as a link in the rule.

• Generate with a script new reference pages (only if they don't already exist).
• Each new page displays the name of the rule as a title, the message of the rule as main content, and the content of the rule file in a source block. Manual authoring necessary to complete the information.
• Generate the navigation from the pages list.
• Generate an overview with some helpers to navigate the pages.

Review the Reference guide pages to make them meaningful:

• When applicable, copy over the word usage description from https://redhat-documentation.github.io/supplementary-style-guide/
• When necessary, complete the usage description using the rule source file.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Cite https://source.redhat.com/groups/public/ccs/ccs_wiki/ccs_style_guides_and_term_conventions in the list of definitive sources.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

"Terminal emulation" refers to making a computer respond like a particular type of terminal. Terminal emulation programs allow you to access a mainframe computer or bulletin board service with a personal computer.

Use it: yes

https://redhat-documentation.github.io/supplementary-style-guide/#_t

However the shell-prompt rule is raisinn an error: https://github.com/Vale-at-Red-Hat/vale-at-red-hat/blob/main/.vale/styles/RedHat/shell-prompt.yml

https://redhat-documentation.github.io/supplementary-style-guide/#_a

absolute path (noun)
Description: The location of a file or directory from the root directory (/). Provides all information to locate a file or directory.

Use it: yes

Incorrect forms:

See also:

Document a setup suitable for GitLab.

Linting with vale failing after hanging on pull requests with no content changes for vale (typically changes on rules).

See errata-ai/vale-action#39, https://github.com/Vale-at-Red-Hat/vale-at-red-hat/actions/workflows/vale.yml.