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

Reorganise rules #29

Merged
merged 6 commits into from
Oct 10, 2023
Merged

Reorganise rules #29

merged 6 commits into from
Oct 10, 2023

Conversation

frankharkins
Copy link
Collaborator

@frankharkins frankharkins commented Oct 10, 2023

Summary

This PR makes these rules more useful to writers by splitting them into meaningful groups and improving the explanations.

  • Added working links.

  • Split Terms.yml across a few rules so we can better explain why writers see certain recommendations. Here are the rules and their explanations:

    • Accessibility.yml

      Use '%s' rather than '%s' if referring to position in a document (for screen readers).

    • Recommend.yml

      Avoid '%s'. Instead, describe why the action is problematic or beneficial.

    • UIConsistency.yml

      Use '%s' rather than '%s' if writing about user interfaces.

    • Wordiness.yml

      Try '%s' rather than '%s'.

    • Terms.yml

      Use '%s' rather than '%s' for consistency across IBM Quantum.

    I also removed some terms as they either don't make sense (for example, suggesting to replace with the same word), or are unlikely to ever occur in our documentation.

    Deleted rules
    back-level: earlier|previous|not at the latest level  
    Big Blue: IBM  
    blue screen of death: stop error  
    canned: preplanned|preconfigured|predefined  
    CBE: Common Base Event  
    CBTS: CICS BTS|BTS  
    cold boot: hardware restart  
    cold start: hardware restart  
    demilitarized zone: DMZ  
    fixed disk drive: hard disk drive  
    floppy disk: diskette|diskette drive  
    floppy drive: diskette|diskette drive  
    floppy: diskette|diskette drive  
    i-Fix: interim fix  
    IBM's: IBM's|IBM's AIX  
    instead of: rather than  
    insure: ensure  
    Internet address: IP address|URL|Internet email address|web address  
    offline storage: auxiliary storage  
    perimeter network: DMZ  
    power down: turn on|turn off  
    power off: turn on|turn off  
    power on: turn on|turn off  
    retry: retry|try again  
    Simple Object Access Protocol: SOAP  
    SME routine: session management exit routine  
    toggle off: toggle  
    touchscreen: touch-sensitive screen  
    transparent: indiscernible|not visible  
    zip: zip|compress
  • Renamed CringeWords to BestPractice to avoid implying writing is "cringey".

@frankharkins frankharkins linked an issue Oct 10, 2023 that may be closed by this pull request
2 tasks
Copy link
Collaborator

@abbycross abbycross left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thoughtful changes -- LGTM

@beckykd
Copy link
Collaborator

beckykd commented Oct 10, 2023

My only question regards the "IBM's" rule. It's frequently used incorrectly. See full description here: https://ibm-quantumcomputing.slack.com/archives/C04RC2CCL2U/p1696951256804089?thread_ts=1696944381.471789&cid=C04RC2CCL2U

@frankharkins frankharkins mentioned this pull request Oct 10, 2023
@frankharkins frankharkins merged commit d3d47b7 into main Oct 10, 2023
2 checks passed
@frankharkins frankharkins deleted the fh-reorganize branch October 10, 2023 16:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Clean up rules
3 participants