From a88984db46ca2ffd0d6d6b322044a292b63c12a7 Mon Sep 17 00:00:00 2001 From: Sarah Welton Date: Thu, 15 Feb 2024 16:17:34 -0500 Subject: [PATCH] Updates and improvements based on Alison's feedback. --- ValeStyles/Couchbase/An.yml | 5 +- ValeStyles/Couchbase/UnexplainedAcronym.yml | 86 +++++++++++++++++++ styleguidepages/modules/ROOT/nav.adoc | 1 + .../modules/ROOT/pages/general.adoc | 7 +- .../modules/ROOT/pages/may-can.adoc | 11 +++ .../modules/ROOT/pages/parentheses.adoc | 7 +- .../modules/ROOT/pages/quotation-marks.adoc | 6 +- 7 files changed, 116 insertions(+), 7 deletions(-) create mode 100644 styleguidepages/modules/ROOT/pages/may-can.adoc diff --git a/ValeStyles/Couchbase/An.yml b/ValeStyles/Couchbase/An.yml index 68a5388b..4c4c2985 100644 --- a/ValeStyles/Couchbase/An.yml +++ b/ValeStyles/Couchbase/An.yml @@ -17,4 +17,7 @@ exceptions: - '[Aa] <<[BbCcDdFfGgHhJjKkLlMmNnPpQqRrSsTtVvWwXxYyZz].+>>' - '[Aa] [Oo]ne' - '[Aa] [Oo]nce' - - '[Aa] [Uu]nit\s' \ No newline at end of file + - '[Aa] [Uu]nit\s' + - '[Aa] [Uu]nique' + - '[Aa] [Uu][Ss][Ee]' + - '[Aa] [Uu]niversal' \ No newline at end of file diff --git a/ValeStyles/Couchbase/UnexplainedAcronym.yml b/ValeStyles/Couchbase/UnexplainedAcronym.yml index 4cf1399b..1abb0568 100644 --- a/ValeStyles/Couchbase/UnexplainedAcronym.yml +++ b/ValeStyles/Couchbase/UnexplainedAcronym.yml @@ -10,75 +10,161 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: - NET + - ALL + - AND - API - ASCII - ASP + - ANY + - CALL + - CASE + - CAST - CBQ - CLI + - COPY + - COVER - CPU - CSS - CSV - cURL - DEBUG + - DESC - DITA - DOC - DOM + - DROP - DPI + - EACH + - ELSE + - END + - EVERY + - FALSE - FAQ + - FETCH + - FIRST + - FLUSH + - FOR + - FORCE + - FROM - GCC - GDB - GET - GIF - GNU - GPU + - GRANT + - GROUP - GTK - GUI + - HASH - HTML - HTTP - HTTPS - IDE + - IF + - ILIKE + - INDEX + - INFER + - INNER + - INTO - IP - JAR - JIRA + - JOIN - JPEG - JPG - JSON - JSX + - KEY + - KEYS + - KNOWN + - LAST - LDAP + - LEFT + - LET - LESS + - LEVEL + - LIKE + - LIMIT - LLDB + - MAP + - MERGE + - MINUS - NET + - NEST + - NOT - NOTE + - NULL + - NULLS - NVDA + - ORDER - OSS + - OUTER + - OVER + - PARSE - PATH - PDF - PHP - PNG + - POOL - POST + - PROBE - RAM + - RANGE + - RAW + - REALM - REPL - REST + - RIGHT + - ROLE - ROOT + - ROW + - ROWS - RSA - SCM + - SCOPE - SCSS - SDK + - SELECT + - SELF + - SEMI + - SET + - SHOW + - SOME - SQL - SSH + - START - SSL - SVG - TBD + - THEN + - TIES - TIP - TCP - TLS - TODO + - TRAN + - TRUE - UUID + - UNDER + - UNION + - UNSET - URI - URL - USB + - USE + - USER - UTF + - VALUE + - VIA + - VIEW + - WHEN + - WHERE + - WHILE + - WITH + - WORK - XML + - XOR - XSS - YAML - ZIP \ No newline at end of file diff --git a/styleguidepages/modules/ROOT/nav.adoc b/styleguidepages/modules/ROOT/nav.adoc index 2553c357..21585a57 100644 --- a/styleguidepages/modules/ROOT/nav.adoc +++ b/styleguidepages/modules/ROOT/nav.adoc @@ -9,6 +9,7 @@ ** xref:capitalization.adoc[] ** xref:contractions.adoc[] ** xref:less-fewer.adoc[] +** xref:may-can.adoc[] ** xref:only.adoc[] ** xref:there-is.adoc[] ** xref:which-that.adoc[] diff --git a/styleguidepages/modules/ROOT/pages/general.adoc b/styleguidepages/modules/ROOT/pages/general.adoc index 3f58efc4..700e5df9 100644 --- a/styleguidepages/modules/ROOT/pages/general.adoc +++ b/styleguidepages/modules/ROOT/pages/general.adoc @@ -9,6 +9,9 @@ The following are some general principles of writing in the Couchbase Style: * <> * <> +As well, try to write using ventilated prose. +This means entering every sentence on a new line in your AsciiDoc files. + == Write in American English Use American English spelling, not British or Canadian English. The Vale automated spellcheck uses an American English dictionary. @@ -18,7 +21,7 @@ If you need to check the spelling of a word, refer to the https://www.merriam-we If Vale flags a product name or other technical industry term as incorrect: * If it's a phrase or single word that must have specific capitalization, add it to the `Vocab\Couchbase\accept.txt` file. -* If it's a phrase that needs a specific arrangement of hyphens or spaces and the capitalization doesn't matter, add it to the `Couchbase\Terminology.yml` Vale Style. +* If it's a phrase that needs a specific arrangement of hyphens or spaces and the capitalization does not matter, add it to the `Couchbase\Terminology.yml` Vale Style. == Write in the Present Tense @@ -97,7 +100,7 @@ Here are some tips to help you with active voice: * Think about what's actually _doing_ the action you're describing. Emphasize the actor. * Find or push back for more information if you cannot identify the actor. Ask the developer what's actually doing what in a scenario. -* If the sentence doesn't make sense in active voice or you lose the correct emphasis, you can use the passive voice. +* If the sentence does not make sense in active voice or you lose the correct emphasis, you can use the passive voice. For more information about active voice, see https://developers.google.com/style/voice[Active voice^] in the Google Developer Style Guide. diff --git a/styleguidepages/modules/ROOT/pages/may-can.adoc b/styleguidepages/modules/ROOT/pages/may-can.adoc new file mode 100644 index 00000000..91f3e5d8 --- /dev/null +++ b/styleguidepages/modules/ROOT/pages/may-can.adoc @@ -0,0 +1,11 @@ += May vs. Can + +Do not use *may* and *can* interchangeably. +They mean different things: + +* Use *may* to convey a possibility, or something that could or might happen. ++ +For example, it *may* rain tomorrow. +* Use *can* to convey ability, or something that the user is able to accomplish. ++ +For example, a user *can* delete a database. \ No newline at end of file diff --git a/styleguidepages/modules/ROOT/pages/parentheses.adoc b/styleguidepages/modules/ROOT/pages/parentheses.adoc index 157ea5e9..52357af4 100644 --- a/styleguidepages/modules/ROOT/pages/parentheses.adoc +++ b/styleguidepages/modules/ROOT/pages/parentheses.adoc @@ -2,10 +2,13 @@ Use parentheses sparingly. -Don't use parentheses to set off an aside or comment in text. Use an xref:dashes.adoc[em dash], instead. +Do not use parentheses to set off an aside or comment in text. Use an xref:dashes.adoc[em dash], instead. You must use parentheses when you mention an unfamiliar acronym for the first time in your documentation. For example, `the Alphabet Biscuit Club (ABC)`. Parentheses are always acceptable when used inside code blocks. -Don't add parentheses to xref:headings.adoc[]. \ No newline at end of file +Do not add parentheses to xref:headings.adoc[]. + +NOTE: Parentheses are acceptable in situations where you may be describing a SQL++ statement with an optional keyword. +When in doubt, use your best judgment around parentheses, and ignore the Vale flags. \ No newline at end of file diff --git a/styleguidepages/modules/ROOT/pages/quotation-marks.adoc b/styleguidepages/modules/ROOT/pages/quotation-marks.adoc index 643942ee..a1619daa 100644 --- a/styleguidepages/modules/ROOT/pages/quotation-marks.adoc +++ b/styleguidepages/modules/ROOT/pages/quotation-marks.adoc @@ -1,5 +1,7 @@ = Quotation Marks -Don't use quotation marks outside of inline code or code blocks. +Do not use quotation marks outside of inline code or code blocks. -Use other emphasis options, such as xref:bold.adoc[] or xref:monospace-highlight.adoc[]. \ No newline at end of file +Use other emphasis options, such as xref:bold.adoc[] or xref:monospace-highlight.adoc[]. + +NOTE: When you're writing JSON, you will use quotation marks everywhere. Make sure to enclose your JSON in a code block or use xref:monospace-highlight.adoc[]. \ No newline at end of file