redhat-documentation / supplementary-style-guide

This project maintains the Red Hat supplementary style guide for product documentation that supplements the IBM Style guide
https://redhat-documentation.github.io/supplementary-style-guide/
Creative Commons Attribution Share Alike 4.0 International
36 stars 74 forks source link

Proposal to update term "binary executable file" to "executable" in supplementary style guidelines and Vale rules #396

Closed rolfedh closed 1 year ago

rolfedh commented 1 year ago

Description:

The term executable is commonly used and understood among our customers and contributors. Currently, the supplementary style guide uses the term "binary executable file" and IBM Style states: image.

Problem Statement:

Proposed Solution:

Update the supplementary style guidelines and Vale rules to allow the use of the term executable as an acceptable alternative to "binary executable file."

Justification:

  1. Simplifies terminology without sacrificing clarity.
  2. Enhances user experience by using commonly understood terms.
  3. Saves time for both contributors and reviewers.

Action Items:

  1. Modify the supplementary style guide to include executable as an accepted term.
  2. Update Vale rules to accommodate this change.
  3. Communicate the update to all contributors and reviewers.

By implementing this change, we can streamline the contribution process and enhance readability.

michelle-purcell commented 1 year ago

+1 @rolfedh - Executable (noun form) is extremely widely used and seems to be preferred by developer audiences within Red Hat, our technology partners, and competitors. Thanks for raising this :+1:

mportman12 commented 1 year ago

Discussed at the September Style Council meeting. Decided that we should write out “binary executable file (executable)” on first use and then just “executable” after that. @rolfedh Can you create a PR for this?

mportman12 commented 1 year ago

PR has been merged, closing this issue.