diff --git a/IBMQuantum/Accessibility.yml b/IBMQuantum/Accessibility.yml new file mode 100644 index 0000000..aafe252 --- /dev/null +++ b/IBMQuantum/Accessibility.yml @@ -0,0 +1,15 @@ +extends: substitution +message: Use '%s' rather than '%s' if referring to position in a document (for screen readers). +link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' +level: warning +ignorecase: true +action: + name: replace +# swap maps tokens in form of bad: good +swap: + 'down(?:-)?level': earlier|previous|not at the latest level + 'down(?:-)?level': earlier|previous|not at the latest level + bottom: end|last + below: following + above: previous + top: start|beginning|first diff --git a/IBMQuantum/CringeWords.yml b/IBMQuantum/BestPractice.yml similarity index 100% rename from IBMQuantum/CringeWords.yml rename to IBMQuantum/BestPractice.yml diff --git a/IBMQuantum/Latin.yml b/IBMQuantum/Latin.yml index b0d2b2b..79b183b 100644 --- a/IBMQuantum/Latin.yml +++ b/IBMQuantum/Latin.yml @@ -10,4 +10,6 @@ swap: '\b(?:eg|e\.g\.)[\s,]': for example '\b(?:ie|i\.e\.)[\s,]': that is '\betc\.': and so on - '\bvs\.': versus + '\bvs\.': compared to + via: through + versus: compared to diff --git a/IBMQuantum/Recommend.yml b/IBMQuantum/Recommend.yml new file mode 100644 index 0000000..c2eac73 --- /dev/null +++ b/IBMQuantum/Recommend.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't use '%s'; we should not recommend to users." +link: 'https://github.com/IBM/ibm-quantum-style-guide/issues/22' # TODO +ignorecase: true +scope: sentence +level: warning +tokens: + - recommend diff --git a/IBMQuantum/Terms.yml b/IBMQuantum/Terms.yml index 06b76f0..d08ca57 100644 --- a/IBMQuantum/Terms.yml +++ b/IBMQuantum/Terms.yml @@ -1,5 +1,5 @@ extends: substitution -message: Use '%s' rather than '%s' +message: Use '%s' rather than '%s' for consistency across IBM Quantum. link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' level: warning ignorecase: true @@ -7,177 +7,98 @@ action: name: replace # swap maps tokens in form of bad: good swap: - '(?:Ctrl|control)-click': press Ctrl and click - 'a lot(?: of)?': many|much - 'backward(?:-)?compatible': compatible with earlier versions - 'down(?:-)?level': earlier|previous|not at the latest level - 'mash(?: )?up': create - 'pop-up (?:blocker|killer)': software to block pop-up ad windows - 're(?:-)?occur': recur - 'sort(?:-|/)?merge': sort|merge - - bottom: end|last - below: following - above: previous - top: start|beginning|first - a number of: several - abort: cancel|stop - administrate: administer - all caps: uppercase - and/or: a or b|a, b, or both - as long as: if|provided that - as per: according to|as|as in - back-level: earlier|previous|not at the latest level - Big Blue: IBM - blink: flash - blue screen of death: stop error - breadcrumbing: breadcrumb trail - canned: preplanned|preconfigured|predefined - case insensitive: not case-sensitive - catastrophic error: unrecoverable error - CBE: Common Base Event - CBTS: CICS BTS|BTS - cold boot: hardware restart - cold start: hardware restart - comes with: includes - componentization: component-based development|component model|component architecture|shared components - componentize: develop components - comprised of: consist of - connect with: connect to - context menu: menu|pop-up menu - contextual help: help|context-sensitive help - crash: fail|lock up|stop|stop responding - CRUD: create retrieve update and delete - customer: client - datum: data - debuggable: debug - deconfigure: unconfigure - deinstall: uninstall - deinstallation: uninstallation - demilitarized zone: DMZ - demo: demonstration - depress: press|type - deregister: unregister - desire: want|required - destroy: delete from the database - dismount: demount|unmount|remove - downgrade: upgrade|fallback|fall back|rollback|roll back - downward compatible: compatible with earlier versions - drag and drop: drag - drill up: navigate - e-fix: fix|interim fix - eFix: fix|interim fix - end user: user - end-user interface: graphical interface|interface - EUI: graphical user interface|interface - expose: display|show|make available - fill in: complete|enter|specify - fixed disk drive: hard disk drive - flavor: version|method - floppy disk: diskette|diskette drive - floppy drive: diskette|diskette drive - floppy: diskette|diskette drive - forward compatible: compatible with later versions - gzip: compress - gzipped: archive|compressed file - hard drive: hard disk|hard disk drive - hard file: hard disk|hard disk drive - hence: therefore - i-fix: interim fix - i-Fix: interim fix - IBM's: IBM's|IBM's AIX - ifix: interim fix - iFix: interim fix - in order to: to - in other words: for example|that is - in spite of: regardless of|despite - in the event: in case|if|when - inactivate: deactivate - information on: information about - information technology: IT - instead of: rather than - insure: ensure - Internet address: IP address|URL|Internet email address|web address - irrecoverable: unrecoverable - jar: compress|archive - keep in mind: remember - launch: start|open - left-hand: left - leverage: use - line cord: power cable|power cord - main directory: root directory - memory stick: USB flash drive - microcomputer: PC - motherboard: system board - mouse over: point to|move the mouse pointer over|Mouse|mouse over - network-centric computing: network computing - non-English: in languages other than English|non-English-language - nonrecoverable: unrecoverable - notion: concept - off-premise: on-premises|off-premises|onsite|offsite - offline storage: auxiliary storage - okay: OK - on ramp: access method - on the fly: dynamically|as needed|in real time|immediately - on the other hand: however|alternatively|conversely - on-premise: on-premises|off-premises|onsite|offsite - on-ramp: access method - pain point: challenge|concern|difficulty|issue - parent task: parent process - patch: fix|test fix|interim fix|fix pack|program temporary fix - perimeter network: DMZ - power down: turn on|turn off - power off: turn on|turn off - power on: turn on|turn off - preload: preinstall|preinstalled - preloaded: preinstall|preinstalled - prepend: add a prefix to - prior to: before - recommend: suggest - retry: retry|try again - right double-click: double right-click - right-hand: right - rule of thumb: rule - sanity check: test|evaluate - secondary storage: auxiliary storage - selection button: left mouse button - serial database: nonpartitioned database environment - set-up: setup - shift-click: press Shift and click - ship: include|included - Simple Object Access Protocol: SOAP - single quote mark: single quotation mark - single quote: single quotation mark - SME routine: session management exit routine - start up: start - sunset: withdraw from service|withdraw from marketing|discontinue|no longer support - switch off: power on|turn on|power off|turn off - switch on: power on|turn on|power off|turn off - tar: compress|archive - tarball: tar file - terminate: end|stop - thru: through - thumbstick: USB flash drive - thus: therefore - toggle off: toggle - tooling: tools - touchscreen: touch-sensitive screen - transparent: indiscernible|not visible - typo: typing error|typographical error - uncheck: clear - uncompress: decompress - undeploy: remove|withdraw - unjar: extract - unselect: clear|deselect - untar: extract - unzip: unzip - upward compatible: compatible with later versions - utilize: use - versus: compared to - via: through - warning notice: attention notice - web-enable: enable for the web - webinar: webinar|webcast|web seminar|web-based event - wish: want - zero out: zero - zip: zip|compress + 'backward(?:-)?compatible': compatible with earlier versions + 'mash(?: )?up': create + 'pop-up (?:blocker|killer)': software to block pop-up ad windows + 're(?:-)?occur': recur + 'sort(?:-|/)?merge': sort|merge + abort: cancel|stop + administrate: administer + all caps: uppercase + and/or: a or b|a, b, or both + as per: according to|as|as in + case insensitive: not case-sensitive + catastrophic error: unrecoverable error + comes with: includes + componentization: component-based development|component model|component architecture|shared components + componentize: develop components + connect with: connect to + crash: fail|lock up|stop|stop responding + CRUD: create retrieve update and delete + customer: client + datum: data + debuggable: debug + deconfigure: unconfigure + deinstall: uninstall + deinstallation: uninstallation + demo: demonstration + deregister: unregister + desire: want|required + destroy: delete (data) + dismount: demount|unmount|remove + downgrade: upgrade|fallback|fall back|rollback|roll back + downward compatible: compatible with earlier versions + e-fix: fix|interim fix + eFix: fix|interim fix + end user: user + end-user interface: graphical interface|interface + EUI: graphical user interface|interface + expose: display|show|make available + flavor: version|method + forward compatible: compatible with later versions + gzip: compress + gzipped: archive|compressed file + hard drive: hard disk|hard disk drive + hard file: hard disk|hard disk drive + i-fix: interim fix + ifix: interim fix + inactivate: deactivate + information on: information about + information technology: IT + internet address: IP address|URL|Internet email address|web address + irrecoverable: unrecoverable + jar: compress|archive + line cord: power cable|power cord + main directory: root directory + memory stick: USB flash drive + microcomputer: PC + motherboard: system board + network-centric computing: network computing + non-English: in languages other than English|non-English-language + nonrecoverable: unrecoverable + notion: concept + off-premise: on-premises|off-premises|onsite|offsite + okay: OK + on ramp: access method + on-premise: on-premises|off-premises|onsite|offsite + on-ramp: access method + parent task: parent process + patch: fix|test fix|interim fix|fix pack|program temporary fix + preload: preinstall|preinstalled + preloaded: preinstall|preinstalled + sanity check: test|evaluate + secondary storage: auxiliary storage + serial database: nonpartitioned database environment + set-up: setup + ship: include|included + single quote mark: single quotation mark + single quote: single quotation mark + start up: start + sunset: withdraw from service|withdraw from marketing|discontinue|no longer support + tar: compress|archive + tarball: tar file + thru: through + thumbstick: USB flash drive + tooling: tools + typo: typing error + uncompress: decompress + undeploy: remove|withdraw + unjar: extract + untar: extract + unzip: unzip + upward compatible: compatible with later versions + warning notice: attention notice + web-enable: enable for the web + webinar: webinar|webcast|web seminar|web-based event + wish: want + zero out: zero diff --git a/IBMQuantum/UIConsistency.yml b/IBMQuantum/UIConsistency.yml new file mode 100644 index 0000000..e4f5c1f --- /dev/null +++ b/IBMQuantum/UIConsistency.yml @@ -0,0 +1,29 @@ +extends: substitution +message: Use '%s' rather than '%s' if writing about user interfaces. +link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' +level: warning +ignorecase: true +action: + name: replace +# swap maps tokens in form of bad: good +swap: + '(?:Ctrl|control)-click': press Ctrl and click + blink: flash + breadcrumbing: breadcrumb trail + context menu: menu|pop-up menu + contextual help: help|context-sensitive help + depress: press|type + drag and drop: drag + drill up: navigate + fill in: complete|enter|specify + launch: start|open + left-hand: left + mouse over: point to|move the mouse pointer over|Mouse|mouse over + right double-click: double right-click + right-hand: right + selection button: left mouse button + shift-click: press Shift and click + switch off: turn off + switch on: turn on + uncheck: clear + unselect: clear|deselect diff --git a/IBMQuantum/Wordiness.yml b/IBMQuantum/Wordiness.yml new file mode 100644 index 0000000..d9c5fe7 --- /dev/null +++ b/IBMQuantum/Wordiness.yml @@ -0,0 +1,29 @@ +extends: substitution +message: Try '%s' rather than '%s'. +link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist' +level: warning +ignorecase: true +action: + name: replace +# swap maps tokens in form of bad: good +swap: + 'a lot(?: of)?': many|much + a number of: several + as long as: if|provided that + comprised of: consist of + hence: therefore + in order to: to + in other words: for example|that is + in spite of: regardless of|despite + in the event: in case|if|when + keep in mind: remember + leverage: use + on the fly: dynamically|as needed|in real time|immediately + on the other hand: however|alternatively|conversely + pain point: challenge|concern|difficulty|issue + prepend: add a prefix to + prior to: before + rule of thumb: rule + terminate: end|stop + thus: therefore + utilize: use diff --git a/features/rules.feature b/features/rules.feature index 411d839..424833d 100644 --- a/features/rules.feature +++ b/features/rules.feature @@ -4,17 +4,17 @@ Feature: Rules When I test "Terms" Then the output should contain exactly: """ - test.md:3:13:IBMQuantum.Terms:Use 'end' or 'last' rather than 'bottom' - test.md:5:11:IBMQuantum.Terms:Use 'several' rather than 'a number of' + test.md:3:13:IBMQuantum.Accessibility:Use 'end' or 'last' rather than 'bottom' if referring to position in a document (for screen readers). + test.md:5:11:IBMQuantum.Wordiness:Try 'several' rather than 'a number of'. test.md:11:10:IBMQuantum.Spelling:Unknown word 'algorihm'; fix or add to dictionary. - test.md:15:24:IBMQuantum.Terms:Use 'following' rather than 'below' + test.md:15:24:IBMQuantum.Accessibility:Use 'following' rather than 'below' if referring to position in a document (for screen readers). test.md:19:29:IBMQuantum.However:Double-check your punctuation around 'however' (see github.com/IBM/ibm-quantum-style-guide/issues/10 for more information). test.md:23:16:IBMQuantum.However:Double-check your punctuation around 'however' (see github.com/IBM/ibm-quantum-style-guide/issues/10 for more information). test.md:25:1:IBMQuantum.Politeness:Don't use 'Please' - test.md:27:1:IBMQuantum.CringeWords:Don't use 'We understand that' - test.md:27:36:IBMQuantum.Terms:Use 'use' rather than 'utilize' - test.md:27:75:IBMQuantum.CringeWords:Don't use 'end users' - test.md:27:90:IBMQuantum.CringeWords:Don't use 'we encourage you' + test.md:27:1:IBMQuantum.BestPractice:Don't use 'We understand that' + test.md:27:36:IBMQuantum.Wordiness:Try 'use' rather than 'utilize'. + test.md:27:75:IBMQuantum.BestPractice:Don't use 'end users' + test.md:27:90:IBMQuantum.BestPractice:Don't use 'we encourage you' test.md:29:12:IBMQuantum.Links:Link names should make sense without context; change "link" to something more descriptive. """ @@ -33,9 +33,10 @@ Feature: Rules When I test "Latin" Then the output should contain exactly: """ + test.md:1:21:IBMQuantum.Latin:Use 'through' instead of 'via'. test.md:3:10:IBMQuantum.Latin:Use 'and so on' instead of 'etc.'. test.md:5:31:IBMQuantum.Latin:Use 'that is' instead of 'i.e.,'. - test.md:7:6:IBMQuantum.Latin:Use 'versus' instead of 'vs.'. + test.md:7:6:IBMQuantum.Latin:Use 'compared to' instead of 'vs.'. """ Scenario: Capitalization diff --git a/fixtures/Terms/.vale.ini b/fixtures/Terms/.vale.ini index 79c12ad..a782691 100644 --- a/fixtures/Terms/.vale.ini +++ b/fixtures/Terms/.vale.ini @@ -5,7 +5,11 @@ MinAlertLevel = suggestion [*.md] IBMQuantum.Spelling = YES IBMQuantum.Terms = YES -IBMQuantum.CringeWords = YES +IBMQuantum.Accessibility = YES +IBMQuantum.UIConsistency = YES +IBMQuantum.Wordiness = YES +IBMQuantum.Recommend = YES +IBMQuantum.BestPractice = YES IBMQuantum.Politeness = YES IBMQuantum.However = YES IBMQuantum.Links = YES