Skip to content

Add list of style guide rules #32

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.

Sign up for GitHub

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

Open
kprosise wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add list of style guide rules #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
1 change: 1 addition & 0 deletions style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down