From 12669ea482419726c0475f438903701197d8bbd3 Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Wed, 12 Aug 2026 09:58:28 -0400 Subject: [PATCH] Add list of style guide rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated README.md with what is to be a "living" list of implemented rules and their status. This commit applies to Jira issue FFTK-4813, "…table of style rules" Signed-off-by: Katrina Prosise --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++ style-guide.md | 1 + 2 files changed, 73 insertions(+) diff --git a/README.md b/README.md index 4d0d3d1..ad1aae8 100644 --- a/README.md +++ b/README.md @@ -29,3 +29,75 @@ directory, and then in the users home directory. Vale has [integrations](https://vale.sh/docs/integrations/guide/) with common editors/IDEs. +## Rule Implementation + +The following rules were extracted from the style guide. +Below is their status as of 2026 August: + +| Rule | Added | File | Type | +| :---: | :---: | :---: | :---: | +| Preset tense | no | -- | skill | +| Active voice | no | -- | both | +| American Spelling | no | -- | both | +| Em dash | yes | `em-dash.yml` | linter | +| En dash | yes | `en-dash.yml` | linter | +| Em dash tic | no | -- | skill | +| Excessive commas | no | -- | both | +| Oxford comma | yes | `oxford-comma.yml` | linter | +| Acronyms | yes | `expand-acronyms.yml` | linter | +| Branding and Names | yes | `branding-and-names.yml` | linter | +| Trademarks | partial | multiple | linter | +| Nosuchthing as secure | parital | `security-focused.yml` | both | +| No gurantees | yes | `help-not-ensure.yml` | linter | +| No duplicate headers | no | -- | linter | +| Min repeated content | no | -- | both | +| Image descriptors | no | -- | both | +| Ambiguous language | yes | `ambigous-language.yml` | linter | +| Matching tone/voice | no | -- | both | +| Avoid idioms | no | -- | both | +| Limit metaphors | no | -- | skill | +| Avoid contractions | yes | `Contractions.yml` | linter | +| Sentence length | partial | `sentence-length.yml` | both | +| Wordiness | no | -- | both | +| Inclusive language | yes | `InclusiveLanguage.yml` | linter | +| No "click here" | yes | `No-click-here.yml` | linter | +| Excessive links | no | -- | linter | +| Attribution | no | -- | skill | +| Avoid Humor | no | -- | skill | +| Negative Contrastive language | no | -- | skill | +| Precede list with colon | no | -- | linter | +| Limit list depth | no | -- | linter | +| Enumerate steps | no | -- | skill | +| Letter options | no | -- | skill | +| Bulleted list | no | -- | skill | +| List punctuation | no | -- | skill | +| Table rules | no | -- | skill | +| Header Capitalization | yes | `Header-cap.yml` | linter | +| cli option bullet list | no | -- | skill | +| host example format | no | -- | skill | +| device example format | no | -- | skill | +| root example format | no | -- | skill | +| Pygments syntax choice | no | -- | skill | +| italics usage | no | -- | both | +| Bold usage | no | -- | both | +| tip admonition | no | -- | skill | +| warning admonition | no | -- | skill | +| note admonition | no | -- | skill | +| Semantic line breaks | no | -- | both | +| Line Column Length | no | -- | both | +| Dictionary | no | -- | resource | +| Agent Glossary | no | -- | resource | + +**Rule** states the guideline in less than four words; +consult the style guide for explanations. + +**Added** summarizes their implementation status. + +**File** indicates file name. +Linter rules are found `Fio-docs/`. + +**Type** indicates if it is a linter rule, +Agent skill file, both, or a shared resource. +Agent skills are either "linter-like", meant to assist with editing existing content, +or content generation skills. +The resource type are for human, linter, and Agent, and serve to provide a vocabulary. diff --git a/style-guide.md b/style-guide.md index 885c138..80a3b37 100644 --- a/style-guide.md +++ b/style-guide.md @@ -184,6 +184,7 @@ Best practices: - Avoid ambiguous language, and be mindful of metaphors and phrases that may not translate. - Match the voice/tone with that of the surrounding content. +- Avoid Negative contrastive language, a common AI tic. ### Sentence Length