diff --git a/.gitignore b/.gitignore index ffa80b87f..1b4eeb580 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ Gemfile.lock .vale modules/.vale.ini .vale.ini +.claude +.cursor \ No newline at end of file diff --git a/.rulesync/skills/doc-create/SKILL.md b/.rulesync/skills/doc-create/SKILL.md new file mode 100644 index 000000000..1ee1fe7e3 --- /dev/null +++ b/.rulesync/skills/doc-create/SKILL.md @@ -0,0 +1,104 @@ +--- +name: doc-create +description: Create new documentation pages for the validatedpatterns.io site. Supports learn pages and pattern page sets. Generates AsciiDoc files with correct frontmatter, structure, and style-compliant content. Use when creating new docs, pages, patterns, or learn content. +argument-hint: +--- + +Create new documentation for the validatedpatterns.io Hugo site. Follow the workflow below precisely. + +--- + +## Step 1: Resolve content type and gather inputs + +- If `$ARGUMENTS` is empty, ask the user what content type (`learn` or `pattern`) and topic to create. +- If `$ARGUMENTS` contains a content type and topic, use them directly. + +### Learn pages + +Collect: +- **title** (required): Page title in sentence-style capitalization. +- **parent menu** (optional): If this is a child page, the parent menu label (e.g. "Patterns quick start"). Leave empty for top-level learn pages. +- **weight** (required): Sort order (10, 20, 30, ...). +- **topic summary**: Brief description of what the page covers — used to generate content. + +### Pattern page sets + +Collect: +- **pattern name** (required): Lowercase, dash-separated directory name (e.g. `my-new-pattern`). +- **title** (required): Human-readable pattern title. +- **date** (required): Publication date in `YYYY-MM-DD` format. +- **summary** (required): One-sentence pattern description. +- **tier** (required): `sandbox`, `tested`, or `maintained`. +- **rh_products** (required): List of Red Hat products used. +- **industries** (required): List of target industries. +- **partners** (optional): List of partner organizations. +- **GitHub repo URL** (required): Used to populate `links.github` and `links.bugs`. +- **Additional subpages** (optional): Beyond the standard set (getting-started, cluster-sizing, ideas-for-customization, troubleshooting). + +## Step 2: Determine format and naming + +- **Always use AsciiDoc (`.adoc`)** unless the user explicitly requests Markdown (`.md`). +- File names: lowercase, dash-separated (e.g. `getting-started.adoc`, `cluster-sizing.adoc`). +- Pattern directories: `content/patterns//` with `_index.adoc` and subpages. +- Learn pages: `content/learn/.adoc`. + +## Step 3: Generate files from templates + +Read the applicable reference file before generating content: + +- **Learn page**: Read [references/learn-page.md](references/learn-page.md) for frontmatter schema, menu hierarchy, and body structure. +- **Pattern page set**: Read [references/pattern-set.md](references/pattern-set.md) for index frontmatter schema, standard subpages, and body templates. + +### Generation rules + +1. Create files using the template structure, substituting the gathered metadata. +2. For patterns, create the full standard page set: + - `_index.adoc` — pattern overview + - `getting-started.adoc` (weight 10) — prerequisites and deployment procedure + - `cluster-sizing.adoc` (weight 20) — resource requirements + - `ideas-for-customization.adoc` (weight 30) — customization suggestions + - `troubleshooting.adoc` (weight 40) — common issues and solutions + - Plus any additional subpages requested by the user. +3. For AsciiDoc files, always include these attributes at the top of the body: + ``` + :toc: + :imagesdir: /images + :_content-type: ASSEMBLY + include::modules/comm-attributes.adoc[] + ``` +4. **Write real content** based on the topic — not just placeholder comments. Draft substantive sections that the user can refine. Use shared AsciiDoc attributes from `modules/comm-attributes.adoc` instead of hard-coding product names. +5. Use `[id="section-id"]` anchors before major AsciiDoc sections. + +## Step 4: Quick style check + +Before presenting the result, read these high-impact style guides from `../doc-review/guides/` and verify the generated content complies: + +| Priority | Guide | Key check | +|---|---|---| +| 1 | `titles-and-headings.md` | Gerund headings for procedures, noun phrases for concepts | +| 2 | `capitalization.md` | Sentence-style capitalization in all headings | +| 3 | `minimalism.md` | No self-referential text, no fluff, concise sentences | +| 4 | `passive-voice.md` | Active voice in instructions | +| 5 | `future-tense.md` | Present tense throughout | +| 6 | `contractions.md` | No contractions | +| 7 | `avoid-these-words.md` | No banned words | +| 8 | `conscious-language.md` | Inclusive terminology | + +Fix any violations in the generated files before presenting them. + +## Step 5: Full style review with doc-review + +After generating the files, run the **doc-review** skill against all created files for a comprehensive review using the full set of 24 style guides. This catches issues beyond the quick check in Step 4 (e.g. phrasal verbs, comma usage, possessives, link text, UI element formatting, command-line conventions, and format-specific rules). + +Invoke the doc-review skill with the path to the created files: +- For a learn page: pass the single file path (e.g. `content/learn/page-name.adoc`). +- For a pattern page set: pass the pattern directory (e.g. `content/patterns/pattern-name/`). + +Apply must-fix issues automatically. Present recommended improvements to the user for their decision. + +### Output summary + +After generating and validating, present: +1. A file list with full paths and a one-line description of each file. +2. Any style fixes that were applied during generation and review. +3. Suggested next steps (e.g. adding images, creating reusable modules, running `make serve` to preview). diff --git a/.rulesync/skills/doc-create/references/learn-page.md b/.rulesync/skills/doc-create/references/learn-page.md new file mode 100644 index 000000000..2b9df53b4 --- /dev/null +++ b/.rulesync/skills/doc-create/references/learn-page.md @@ -0,0 +1,153 @@ +# Learn page reference + +## Frontmatter + +### Top-level learn page + +```yaml +--- +menu: learn +title: Page title in sentence case +weight: 10 +aliases: /learn/page-name/ +--- +``` + +### Child learn page (nested under a parent) + +```yaml +--- +menu: + learn: + parent: Parent Menu Label +title: Page title in sentence case +weight: 20 +aliases: /learn/page-name/ +--- +``` + +### Optional fields + +| Field | When to use | +|---|---| +| `layout: default` | Only if the page needs a non-standard layout (e.g. landing pages like `quickstart.adoc`) | +| `aliases` | Add an alias matching the old URL if migrating content, or `/learn//` for clean URLs | + +### Known parent menu labels + +These parent labels exist in the current site — use them exactly as shown when creating child pages: + +- `Patterns quick start` +- `Validated patterns frameworks` + +## AsciiDoc body template + +```asciidoc +--- +menu: learn +title: Page title +weight: 10 +--- + +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="page-anchor-id"] += Page title + +Introductory paragraph explaining the purpose and scope of this page. Focus on what the user can accomplish. + +[id="first-section"] +== First section heading + +Content here. Use: + +* Bulleted lists for related items. +* `[source,terminal]` blocks for commands. +* `.Prerequisites` and `.Procedure` labels for procedural sections. + +[id="second-section"] +== Second section heading + +Additional content. +``` + +### Procedural section example + +```asciidoc +[id="deploying-the-component"] +== Deploying the component + +.Prerequisites + +* An OpenShift cluster with dynamic `StorageClass` provisioning. +* The `oc` CLI installed and authenticated. + +.Procedure + +. Clone the repository: ++ +[source,terminal] +---- +$ git clone +---- + +. Change to the project directory: ++ +[source,terminal] +---- +$ cd +---- + +. Deploy the pattern: ++ +[source,terminal] +---- +$ ./pattern.sh make install +---- +``` + +### Concept section example + +```asciidoc +[id="benefits-of-gitops"] +== Benefits of GitOps + +GitOps provides the following advantages: + +* **Declarative configuration**: The desired state is stored in Git. +* **Auditability**: Every change is tracked through Git history. +* **Automation**: Changes are automatically applied by the GitOps operator. +``` + +## Markdown body template + +Use only when the user explicitly requests Markdown. + +```markdown +--- +menu: learn +title: Page title +weight: 10 +--- + +# Page title + +Introductory paragraph explaining the purpose and scope of this page. + +## First section heading + +Content here. + +## Second section heading + +Additional content. +``` + +## Naming conventions + +- File names: lowercase, dash-separated (e.g. `getting-started-with-gitops.adoc`). +- Placed directly in `content/learn/` (flat structure, no subdirectories). +- Use descriptive names that reflect the content (e.g. `secrets-management.adoc`, not `secrets.adoc`). diff --git a/.rulesync/skills/doc-create/references/pattern-set.md b/.rulesync/skills/doc-create/references/pattern-set.md new file mode 100644 index 000000000..4faa48fd3 --- /dev/null +++ b/.rulesync/skills/doc-create/references/pattern-set.md @@ -0,0 +1,278 @@ +# Pattern page set reference + +A pattern page set lives in `content/patterns//` and consists of an index page plus standard subpages. + +## Index page: `_index.adoc` + +### Frontmatter + +```yaml +--- +title: Pattern Title +date: 2025-10-24 +tier: sandbox +summary: One-sentence description of what this pattern does. +rh_products: + - Red Hat OpenShift Container Platform +industries: + - General +partners: + - Partner Name +aliases: /pattern-name/ +pattern_logo: pattern-name.png +links: + github: https://github.com/validatedpatterns/pattern-name + install: getting-started + bugs: https://github.com/validatedpatterns/pattern-name/issues + feedback: https://docs.google.com/forms/d/e/1FAIpQLScI76b6tD1WyPu2-d_9CCVDr3Fu5jYERthqLKJDUGwqBg7Vcg/viewform +--- +``` + +### Required fields + +| Field | Description | +|---|---| +| `title` | Human-readable pattern name | +| `date` | Publication date (`YYYY-MM-DD`) | +| `tier` | `sandbox`, `tested`, or `maintained` | +| `summary` | One-sentence description | +| `rh_products` | List of Red Hat products | +| `industries` | List of target industries | +| `links.github` | GitHub repository URL | +| `links.install` | Slug of the getting-started page (no extension) | +| `links.bugs` | GitHub issues URL | +| `links.feedback` | Feedback form URL (use the standard Google Form URL above) | + +### Optional fields + +| Field | When to use | +|---|---| +| `partners` | Pattern involves partner technology | +| `pattern_logo` | Logo image filename (placed in `static/images/`) | +| `ci` | CI identifier (maintained patterns only) | +| `validated` | Set to `false` for unvalidated sandbox patterns | +| `variant_of` | Parent pattern name if this is a variant (e.g. `variant_of: multicloud-gitops`) | +| `links.arch` | Architecture diagram URL | + +### AsciiDoc body + +```asciidoc +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +Overview paragraph describing the pattern, its purpose, and the problem it solves. Focus on what the user can accomplish. + +== Background + +Explain the business or technical context that motivates this pattern. + +== Next steps + +* link:getting-started[Getting started] +* link:cluster-sizing[Cluster sizing] +``` + +--- + +## Standard subpages + +### `getting-started.adoc` (weight 10) + +```yaml +--- +title: Getting started +weight: 10 +aliases: /pattern-name/getting-started/ +--- +``` + +```asciidoc +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="deploying-pattern-name"] +== Deploying the pattern + +.Prerequisites + +* An OpenShift cluster +** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console] and select *Services -> Containers -> Create cluster*. +** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. +** link:../cluster-sizing[Cluster sizing] requirements. +* https://validatedpatterns.io/learn/quickstart/[Install the tooling dependencies]. + +.Procedure + +. Fork the https://github.com/validatedpatterns/pattern-name[pattern-name] repository on GitHub. + +. Clone the forked repository: ++ +[source,terminal] +---- +$ git clone git@github.com:/pattern-name.git +---- + +. Change to the pattern directory: ++ +[source,terminal] +---- +$ cd pattern-name +---- + +. Deploy the pattern: ++ +[source,terminal] +---- +$ ./pattern.sh make install +---- + +[id="next-steps"] +== Next steps + +* link:../ideas-for-customization[Ideas for customization] +* link:../troubleshooting[Troubleshooting] +``` + +### `cluster-sizing.adoc` (weight 20) + +```yaml +--- +title: Cluster sizing +weight: 20 +aliases: /pattern-name/cluster-sizing/ +--- +``` + +```asciidoc +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="cluster-sizing"] +== Cluster sizing for pattern-name + +The minimum requirements for running this pattern are listed in the following table. + +.Minimum cluster requirements +[options="header"] +|=== +| Node role | Count | CPU | Memory | Storage +| Control plane | 3 | 4 vCPU | 16 GB | 100 GB +| Worker | 3 | 8 vCPU | 32 GB | 200 GB +|=== + +[NOTE] +==== +These are minimum requirements. Production deployments may require additional resources depending on workload. +==== +``` + +### `ideas-for-customization.adoc` (weight 30) + +```yaml +--- +title: Ideas for customization +weight: 30 +aliases: /pattern-name/ideas-for-customization/ +--- +``` + +```asciidoc +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="ideas-for-customization"] +== Ideas for customizing the pattern + +This pattern can be extended and adapted for different use cases. + +=== Adding additional applications + +You can deploy additional applications by editing the `values-hub.yaml` file and adding entries under the `applications` section. + +=== Modifying the GitOps configuration + +You can adjust the ArgoCD application settings by modifying the Helm chart values in the pattern repository. + +[id="next-steps"] +== Next steps + +* link:../getting-started[Getting started] +* link:../troubleshooting[Troubleshooting] +``` + +### `troubleshooting.adoc` (weight 40) + +```yaml +--- +title: Troubleshooting +weight: 40 +aliases: /pattern-name/troubleshooting/ +--- +``` + +```asciidoc +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +[id="troubleshooting"] +== Troubleshooting the pattern + +[id="common-issues"] +=== Checking the deployment status + +To verify that all components deployed successfully, run: + +[source,terminal] +---- +$ oc get pods -A | grep -v Running | grep -v Completed +---- + +[id="reviewing-logs"] +=== Reviewing application logs + +To check the logs of a specific application pod: + +[source,terminal] +---- +$ oc logs -n +---- + +[id="known-issues"] +=== Known issues + +List any known issues and workarounds here. +``` + +--- + +## Naming conventions + +Two naming styles are used across existing patterns: + +| Style | Example | When to use | +|---|---|---| +| Short names | `getting-started.adoc` | Preferred for new patterns | +| Prefixed names | `mcg-getting-started.adoc` | When the pattern has a well-known abbreviation | + +If using prefixed names, apply the prefix consistently to all subpages. + +## Markdown variants + +When the user explicitly requests Markdown, use `.md` extensions and adapt the body: + +- Replace AsciiDoc attributes with standard Markdown syntax. +- Use `#`, `##`, `###` headings instead of `=`, `==`, `===`. +- Use fenced code blocks with language identifiers instead of `[source,...]` blocks. +- Use standard Markdown lists instead of AsciiDoc ordered (`.`) and continuation (`+`) syntax. +- Use `_index.md` for the index page. +- Hugo shortcodes (`{{< note >}}`, `{{< warning >}}`) replace AsciiDoc admonitions (`[NOTE]`, `[WARNING]`). diff --git a/.rulesync/skills/doc-review/SKILL.md b/.rulesync/skills/doc-review/SKILL.md new file mode 100644 index 000000000..826a55867 --- /dev/null +++ b/.rulesync/skills/doc-review/SKILL.md @@ -0,0 +1,118 @@ +--- +name: doc-review +description: Review and fix documentation files against Red Hat/IBM Style Guide rules. Supports both AsciiDoc (.adoc) and Markdown (.md, .markdown) files with format-aware rule application. +argument-hint: +claudecode: + allowed-tools: + - Glob + - Grep + - Read + - Edit +--- + +Review the documentation file(s) at `$ARGUMENTS` for compliance with the Red Hat/IBM Style Guide. Follow the workflow below precisely. + +--- + +## Step 1: Resolve targets + +- If `$ARGUMENTS` is empty, ask the user which file(s) or directory to review. +- If `$ARGUMENTS` is a **directory**, recursively glob for all `*.adoc`, `*.md`, and `*.markdown` files. +- If `$ARGUMENTS` is a **file**, use it directly. +- If no matching files are found, inform the user and stop. + +## Step 2: Detect format and load rules + +For each file, detect the format by extension: + +| Extension | Format | +|---|---| +| `.adoc` | AsciiDoc | +| `.md`, `.markdown` | Markdown | + +**Read each applicable guide file** listed below for the detailed rules, DO/DON'T examples, and severity levels before reviewing. + +### Universal guides — apply to ALL formats + +| # | Guide file | Topic | +|---|---|---| +| 1 | `guides/anthropomorphism.md` | No human traits for products | +| 2 | `guides/passive-voice.md` | Prefer active voice | +| 3 | `guides/future-tense.md` | Prefer present tense | +| 4 | `guides/phrasal-verbs.md` | Replace with single-word verbs | +| 5 | `guides/contractions.md` | Avoid contractions | +| 6 | `guides/avoid-these-words.md` | Full banned words table | +| 7 | `guides/conscious-language.md` | Inclusive terminology (blocklist/allowlist, primary/secondary) | +| 8 | `guides/colons-and-semicolons.md` | Colon and semicolon usage | +| 9 | `guides/commas-restrictive-nonrestrictive.md` | Which vs. that, comma rules | +| 10 | `guides/possessives-and-apostrophes.md` | No 's on product/brand names | +| 11 | `guides/titles-and-headings.md` | Gerunds for procedures, nouns for concepts | +| 12 | `guides/capitalization.md` | Sentence-style capitalization | +| 13 | `guides/incomplete-sentences.md` | Complete sentences before lists | +| 14 | `guides/parallelism.md` | Consistent grammatical structure in lists | +| 15 | `guides/unordered-lists.md` | Bulleted list conventions | +| 16 | `guides/single-step-procedures.md` | Bullet not numbered for single steps | +| 17 | `guides/optional-and-conditional-steps.md` | "Optional:" and "If" prefixes | +| 18 | `guides/inline-links.md` | Link text, "about" not "on", no "Click here" | +| 19 | `guides/screen-captures.md` | Avoid unnecessary screenshots | +| 20 | `guides/ui-elements.md` | Bold GUI names, correct verbs per element | +| 21 | `guides/command-line.md` | Command verbs, monospace, replaceable values | +| 22 | `guides/minimalism.md` | Conciseness, scannability, customer focus, removing fluff | + +### Format-specific guides — apply ONLY to matching format + +| # | Guide file | Applies to | Topic | +|---|---|---|---| +| 23 | `guides/asciidoc-specific.md` | AsciiDoc only | Admonitions, attributes, user-replaceable values, module descriptions, cross-references. **SKIP entirely for Markdown files.** | +| 24 | `guides/markdown-specific.md` | Markdown only | Heading syntax, bold/italic, links, images, code blocks, list conventions. **SKIP entirely for AsciiDoc files.** | + +## Step 3: Review (Phase 1) + +For each file, read the entire file and identify all style violations. Organize findings using this format: + +--- + +### Documentation review: `` + +**Format detected**: AsciiDoc | Markdown +**Summary**: X issues found (Y must-fix, Z recommended) + +#### Must-fix issues + +**Rule name** (N issues) + +1. **Line N**: `problematic text` → `suggested fix` + _Guide: guide-file-name.md_ + +#### Recommended improvements + +**Rule name** (N issues) + +1. **Line N**: `problematic text` → `suggested fix` + _Guide: guide-file-name.md_ + +--- + +### Severity classification + +- **Must-fix**: Violations of core style rules — anthropomorphism, passive voice in instructions, future tense (when present works), banned words marked "Never", incorrect which/that usage, possessives on product names, title case headings, non-parallel lists, incomplete sentences, "Click here" links, conscious language violations, incorrect UI verbs, single-step numbered lists, unclear or ambiguous content (minimalism) +- **Recommended**: Lower-priority improvements — phrasal verbs, link placement, screenshot usage, minor phrasing, admonition density, formatting consistency, conciseness (redundant phrases, self-referential text, obvious statements, fluff, long sentences, scannability) + +## Step 4: Fix (Phase 2) + +After presenting the review for all files, ask: + +> **Would you like me to apply these fixes?** Options: +> 1. Apply all fixes +> 2. Apply must-fix only +> 3. Let me choose which to apply +> 4. No, just keep the report + +If the user approves fixes, edit the files to resolve the selected issues. After applying fixes, summarize what was changed. + +## References + +For detailed guidance, consult: +- IBM Style Guide +- Red Hat Supplementary Style Guide: https://redhat-documentation.github.io/supplementary-style-guide/ssg.md +- Merriam-Webster Dictionary for spelling diff --git a/.rulesync/skills/doc-review/guides/anthropomorphism.md b/.rulesync/skills/doc-review/guides/anthropomorphism.md new file mode 100644 index 000000000..25a9c6655 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/anthropomorphism.md @@ -0,0 +1,27 @@ +# Anthropomorphism + +Format applicability: [All] +IBM Reference: Language and grammar > Anthropomorphism +Severity: **Must-fix** + +## Rule + +Do not attribute human characteristics to software, products, or inanimate objects. Focus on the user performing the action, not the product. + +## Anthropomorphic verbs to flag + +allows, lets, permits, enables, wants, thinks, knows, decides, is interested in, is capable of + +## Examples + +| DON'T | DO | +|---|---| +| The Placement service allows you to provide tenant isolation. | You can use the Placement service to provide tenant isolation. | +| The speech recognition engine is interested only in the following words. | The speech recognition engine accepts only the following words. | +| The program lets you create templates. | You can create templates by using the program. | + +## Rewrite pattern + +Change "Product allows/lets/enables you to X" to: +- "You can X by using Product" +- "With Product, you can X" diff --git a/.rulesync/skills/doc-review/guides/asciidoc-specific.md b/.rulesync/skills/doc-review/guides/asciidoc-specific.md new file mode 100644 index 000000000..495622441 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/asciidoc-specific.md @@ -0,0 +1,155 @@ +# AsciiDoc-Specific Rules + +Format applicability: [AsciiDoc only] + +These rules apply only to `.adoc` files. Skip all rules in this guide when reviewing Markdown files. + +## Admonitions + +### Valid admonition types + +| Type | Purpose | +|---|---| +| NOTE | Additional guidance or advice that improves configuration, performance, or supportability. | +| IMPORTANT | Advisory information essential to task completion. Users must not disregard. | +| WARNING | Potential system damage, data loss, or support issues. Explain problem, cause, and solution. | +| TIP | Alternative methods or non-obvious techniques. Not essential to using the product. | + +### Rules +- Do NOT use `CAUTION` — it is not fully supported by the Red Hat Customer Portal. +- Keep admonitions **short and concise**. +- Do NOT include procedures inside an admonition. +- Avoid placing **multiple admonitions close together**. Restructure by moving less-important content into the main text. +- Use only **singular** admonition labels (e.g., `NOTE`, never `NOTES`). +- Do NOT start a module or assembly with an admonition. Always include a short description first. + +### Correct AsciiDoc syntax + +```asciidoc +[NOTE] +==== +Text for note. +==== +``` + +**Severity**: Must-fix for CAUTION usage, procedures in admonitions, or missing short descriptions. Recommended for admonition density. + +## Product Name and Version Attributes + +Use shared AsciiDoc attributes from `modules/comm-attributes.adoc` instead of hard-coding product names and versions. + +### Rules +- Every `.adoc` content file should include the shared attributes file: + ```asciidoc + include::modules/comm-attributes.adoc[] + ``` +- Use the attribute form for all product and pattern names, operator names, platform names, and versions defined in `modules/comm-attributes.adoc`. +- Hard-code versions only when they refer to a specific, unchanging version (e.g., "introduced in version 3.2"). + +### Review procedure +1. Read `modules/comm-attributes.adoc` to build a lookup of defined attributes and their values. +2. Scan the reviewed file for any hard-coded string that matches a defined attribute value. +3. Flag each match and suggest the attribute replacement. + +### Common attributes to check for + +| Hard-coded string | Use instead | +|---|---| +| Red Hat OpenShift Container Platform | `{rh-ocp}` or `{ocp}` | +| Red Hat Advanced Cluster Management | `{rh-rhacm-first}` (first use) or `{rh-rhacm}` | +| Red Hat OpenShift GitOps | `{rh-gitops}` or `{rh-gitops-short}` | +| Red Hat Ansible Automation Platform | `{rh-ansible}` or `{ansible}` | +| Red Hat OpenShift Data Foundation | `{rh-ocp-data-first}` or `{ocp-data-short}` | +| Red Hat Enterprise Linux | `{rhel-first}` (first use) or `{rhel-short}` | +| Validated Patterns | `{solution-name-upstream}` | +| Validated Patterns Operator | `{validated-patterns-op}` | +| HashiCorp Vault | `{hashicorp-vault}` or `{hashicorp-vault-short}` | +| OpenShift Virtualization | `{VirtProductName}` | +| Pattern names (e.g. "Multicloud GitOps pattern") | `{mcg-pattern}`, `{med-pattern}`, `{ie-pattern}`, etc. | + +This table covers the most common attributes. Always consult `modules/comm-attributes.adoc` for the full list, as new attributes are added over time. + +### Missing include directive +If a file does not include `modules/comm-attributes.adoc` but uses or should use attributes, flag the missing include as a must-fix. + +**Severity**: Must-fix for missing `include::modules/comm-attributes.adoc[]`. Recommended for hard-coded names or versions that have a defined attribute. + +## User-Replaceable Values + +### Standard format (non-XML) +- Surround with angle brackets: `` +- Separate multi-word values with underscores +- Lowercase unless context requires otherwise +- Use italic monospace formatting + +#### In paragraphs +```asciidoc +Create an Ansible inventory file that is named `/__/inventory/hosts`. +``` + +#### In code blocks +Use `subs="+quotes"` or `subs="normal"` to enable formatting inside code blocks: +```asciidoc +[subs="+quotes"] +---- +$ *oc describe node ____* +---- +``` + +### XML format +For XML code blocks, use `${value_name}` instead of ``: +```asciidoc +[source,xml,subs="+quotes"] +---- +__${ip_address}__ +---- +``` + +**Flag**: User-replaceable values without italic formatting, without angle brackets, or using inconsistent naming (camelCase instead of snake_case). + +**Severity**: Must-fix for missing formatting. Recommended for naming consistency. + +## Module Short Descriptions + +Every module and assembly must include a short description (abstract) between the title and main content. + +### Rules +- At least 2-3 sentences. +- Include user intent: what users must do and why. +- Ensure the product name appears in the title or short description. +- Use active voice and present tense. +- Avoid self-referential language ("This topic covers...", "Use this procedure to..."). +- Avoid feature-focused language ("This product allows you to..."). +- Use customer-centric language ("You can... by..." or "To..., configure..."). + +**Severity**: Must-fix if missing entirely. Recommended for content improvements. + +## Cross-References + +### Internal cross-references +```asciidoc +For more information about , see xref:[]. +``` + +### External links +```asciidoc +For more information about , see link:[]. +``` + +### Rules +- Include cross-references only when necessary. +- If information is critical, include it directly instead of cross-referencing. +- Do NOT use bare URLs — always provide descriptive link text. +- Do NOT use URL shorteners. +- Use `latest` in URLs to Red Hat documentation so links resolve to the latest version. + +**Severity**: Must-fix for bare URLs. Recommended for unnecessary cross-references. + +## Non-Breaking Spaces + +Use `{nbsp}` in product names to prevent awkward line breaks: +```asciidoc +Red{nbsp}Hat Enterprise Linux +``` + +**Severity**: Recommended. diff --git a/.rulesync/skills/doc-review/guides/avoid-these-words.md b/.rulesync/skills/doc-review/guides/avoid-these-words.md new file mode 100644 index 000000000..097379dd0 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/avoid-these-words.md @@ -0,0 +1,99 @@ +# Avoid These Words + +Format applicability: [All] +IBM Reference: Word Usage, Language and grammar +Severity: **Must-fix** for "Never" items. **Recommended** for "Avoid" items. + +## Rule + +Flag and replace the following words and constructions. They cause comprehension problems or are inappropriate in technical documentation. + +## Banned words table (from IBM Style Guide) + +| Word/Phrase | Rule | Replacement | +|---|---|---| +| appears (for UI elements) | Never use for elements on screen | "opens" (for windows), "is displayed" (for elements) | +| as (meaning "because") | Never | "because" | +| desire / desired | Never | "want" / "that you want" | +| e.g. | Never (Latin abbreviation) | "for example" | +| etc. | Never (Latin abbreviation) | "and so on" | +| i.e. | Never (Latin abbreviation) | "that is" | +| may (meaning "might") | Never as synonym for "might" | "might" (possibility) or "can" (ability) | +| once (meaning "when/after") | Never; "once" means "one time" | "when" or "after" | +| please | Never; unnecessary politeness | Remove entirely | +| prior to | Never | "before" | +| should | Avoid | "must" or reword to be more direct | +| simply | Never | Remove entirely | +| since (meaning "because") | Never; "since" refers to time only | "because" | +| and/or | Never | Choose "and" or "or" | +| slash for options (/) | Never | Use "or" or "and" | +| utilize | Never | "use" | +| via | Avoid | "through", "by", "by using", "across" | +| while (meaning "although") | Never; "while" refers to time only | "although" or "though" | +| will | Avoid future tense | Rewrite in present tense (see future-tense.md) | +| would | Avoid | Reword to be more direct | + +## Additional "do not use" words (from Red Hat supplementary style guide) + +### General language and style + +| Word/Phrase | Rule | Replacement | +|---|---|---| +| ACK (as abbreviation) | Do not use as abbreviation for "acknowledgment" | "acknowledgment" in prose; "ACK flag" when referring to TCP packets | +| alright | Colloquial; do not use | "all right" or rephrase | +| as expected | Expectations are relative | "correctly" | +| basically | Filler word; does not add meaning | Remove entirely or rephrase | +| bimonthly | Ambiguous (twice a month or every two months) | "twice a month" or "every two months" | +| biweekly | Ambiguous (twice a week or every two weeks) | "twice a week" or "every two weeks" | +| essentially | Filler word; does not add meaning | Remove entirely | +| exclamation point (!) | Do not use at end of sentences | Rephrase without emphasis punctuation (acceptable when referring to the `!` command) | +| he / she | Gendered pronouns | Reword the sentence to avoid gendered pronouns | +| interesting | Vague; does not show why something is of interest | Use a "Note" admonition or explain why it matters | +| lots of / bunches of | Colloquial | "many" | +| quiescent | Obscure; ambiguous meaning | "inactive", "at rest", "in a known state" — be specific | +| recommend / recommends | Avoid "Red Hat recommends"; be prescriptive | Write directly: "Use X because..." or "Use X when..." | +| regex | Abbreviation | "regular expression" | +| skill set | Unnecessary compound | "skills" or "knowledge" | +| snippet | Informal | "piece" (for small portions) or "excerpt" (for samples from a longer text) | +| softcopy | Dated term | "online" (e.g., "To view the online documentation...") | +| totally | Filler word; does not add meaning | Remove entirely | +| unset | Unclear verb | "clear" (e.g., "clear the checkbox", "the ACK flag cleared") | +| we suggest | Indirect | Be direct: instead of "We suggest that you back up your data", write "Back up your data" | + +### Technical terminology + +| Word/Phrase | Rule | Replacement | +|---|---|---| +| hashbang | Slang | "interpreter directive" (first use: "interpreter directives, also known as shebangs") | +| kerberize / kerberized | Informal verb form | "Kerberos-aware" or "Kerberos-enabled", or rephrase | +| network interface card | Incorrect expansion of NIC | "network interface controller" | +| Puppetize | Unnecessary jargon | Describe the action: "apply Puppet manifests to the system" | +| SSL | Deprecated protocol | "TLS" (Transport Layer Security). Use "SSL" only in historical context. | + +### Deprecated product names and terms + +These terms refer to former or renamed products. Use the current product name instead. + +| Do not use | Use instead | +|---|---| +| ActiveMQ (alone, for JBoss EAP) | "JBoss EAP messaging subsystem" | +| domain mode (JBoss EAP) | "managed domain" | +| HTTP interface (JBoss EAP) | "management console" | +| IBM eServer System i | "IBM Power" | +| IBM eServer System p | "IBM Power" | +| IBM S/390 | "IBM Z" | +| iSeries | "IBM Power" | +| JBoss AMQ | "Red Hat AMQ" | +| Microsoft Windows (for server) | "Windows Server" | +| minion (OpenShift) | "node" | +| native interface (JBoss EAP) | "management CLI" | +| .NET Core (for versions after 3.1) | ".NET" | +| OpenShift Origin | "OKD" | +| pSeries | "IBM Power" | +| Red Hat Container Catalog | "Red Hat Ecosystem Catalog" | +| Red Hat Java | "Red Hat build of OpenJDK" | +| Red Hat JBoss Data Grid (for versions after 7.2) | "Red Hat Data Grid" | +| Red Hat OpenJDK | "Red Hat build of OpenJDK" | +| Red Hat OpenShift Container Storage | "Red Hat OpenShift Data Foundation" | +| standalone mode (JBoss EAP) | "standalone server" | +| zSeries | "IBM Z" | diff --git a/.rulesync/skills/doc-review/guides/capitalization.md b/.rulesync/skills/doc-review/guides/capitalization.md new file mode 100644 index 000000000..0c223d6c4 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/capitalization.md @@ -0,0 +1,22 @@ +# Capitalization + +Format applicability: [All] +IBM Reference: Language and grammar > Capitalization +Severity: **Must-fix** + +## Rule + +Use sentence-style capitalization for all headings and titles. Capitalize only: +- The first word +- Proper nouns (product names, brand names) +- Acronyms + +Do NOT use headline-style (title case) capitalization. + +## Examples + +| DON'T | DO | +|---|---| +| Variables to Be Determined by the Program | Variables to be determined by the program | +| Requirements for Linux and UNIX Operating Systems | Requirements for Linux and UNIX operating systems | +| Composing a Customized RHEL System Image | Composing a customized RHEL system image | diff --git a/.rulesync/skills/doc-review/guides/colons-and-semicolons.md b/.rulesync/skills/doc-review/guides/colons-and-semicolons.md new file mode 100644 index 000000000..b2b204a3a --- /dev/null +++ b/.rulesync/skills/doc-review/guides/colons-and-semicolons.md @@ -0,0 +1,48 @@ +# Colons and Semicolons + +Format applicability: [All] +IBM Reference: Punctuation > Colons +Severity: **Must-fix** for incorrect usage. **Recommended** for stylistic improvements. + +## Colon rules + +### When to use a colon +- After an introduction to a vertical list. +- After an independent clause to introduce an inline list. +- After the label of a note (e.g., "Tip:" or "Note:"). +- Between two independent clauses to show a close relationship. +- To separate units of time and express ratios. + +### Capitalization after a colon +Use lowercase after a colon **unless** the text is: +- An item in a vertical list +- A note that follows a label +- A proper noun +- A quotation +- A subheading or subtitle + +### Placement rules +- Do NOT end headings or titles with a colon. +- Do NOT insert a space before a colon. Insert one space after. +- The clause before a colon must be a complete sentence. + +### Examples + +| DON'T | DO | +|---|---| +| The deletion is final: You cannot restore an element. | The deletion is final: you cannot restore an element. | +| Remember to: encrypt the hard disk and set a password. | Remember to take these security measures: encrypt the hard disk and set a password. | +| Creating test cases: | Creating test cases | + +## Semicolon rules + +Use a semicolon to: +- Separate items in a series when the items contain commas. +- Join two related independent clauses before a conjunctive adverb (however, therefore, otherwise, namely, for example). + +### Examples + +| DON'T | DO | +|---|---| +| You can press the yellow, green, or blue button, the off switch or the mouse button. | You can press the yellow, green, or blue button; the off switch; or the mouse button. | +| Right-click the selected text, then click Text Properties. | Right-click the selected text; then click Text Properties. | diff --git a/.rulesync/skills/doc-review/guides/command-line.md b/.rulesync/skills/doc-review/guides/command-line.md new file mode 100644 index 000000000..a45505f84 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/command-line.md @@ -0,0 +1,30 @@ +# Command Line + +Format applicability: [All] +IBM Reference: Computer interfaces > Commands, parameters, and options in instructions +Severity: **Must-fix** for incorrect verbs and unformatted commands. **Recommended** for "command" word usage. + +## Rule + +### Instructing users to run commands +Use these verbs: **enter**, **run**, **type**, **issue**, or **use**. +Do NOT use: "write", "add", "execute", "do". + +### Formatting +- Command names: **monospace font** (backticks in Markdown, backticks or `[command]` in AsciiDoc). +- Variable/replaceable values: **italic monospace**. +- Use the word "command" only on the **first mention** of a command in a section, or when ambiguous. + +### User-replaceable values +- Surround with angle brackets: `` +- Use underscores for multi-word values: `` +- Lowercase unless context requires otherwise +- Italicize and use monospace + +## Examples + +| DON'T | DO | +|---|---| +| In the command line, write the `restart` command. | On the command line, enter `restart`. | +| Add the `ls` command. If you also want to display hidden files, use the `ls -a` command instead. | To list files in your current directory, run the `ls` command. If you also want to display hidden files, run `ls -a` instead. | +| `# systemctl enable service_name` / Replace service_name with the service. | `# systemctl enable ` / Replace `` with the service that you want to enable. | diff --git a/.rulesync/skills/doc-review/guides/commas-restrictive-nonrestrictive.md b/.rulesync/skills/doc-review/guides/commas-restrictive-nonrestrictive.md new file mode 100644 index 000000000..57ea1041e --- /dev/null +++ b/.rulesync/skills/doc-review/guides/commas-restrictive-nonrestrictive.md @@ -0,0 +1,32 @@ +# Commas in Restrictive and Nonrestrictive Clauses + +Format applicability: [All] +IBM Reference: Commas > Commas with nonrestrictive clauses and phrases +Severity: **Must-fix** for which/that misuse. **Recommended** for parentheses replacement. + +## Rule + +### Nonrestrictive clauses (extra info, removable) +- Use the relative pronoun **"which"**. +- **Surround with commas**. +- If you remove the clause, the basic meaning does not change. + +### Restrictive clauses (essential, not removable) +- Use the relative pronoun **"that"**. +- **No commas**. +- The clause is essential to the sentence meaning. + +## Examples + +| DON'T | DO | +|---|---| +| The Recovery log which is generated automatically shows the cause. | The Recovery log, which is generated automatically, shows the cause. | +| The Recovery log, that contains the most recent information, is in the folder. | The Recovery log that contains the most recent information is in the folder. | + +## Parentheses tip + +Parenthetical text in running prose often signals a nonrestrictive clause. Replace parentheses with commas for better readability and translation. + +| Avoid | Preferred | +|---|---| +| HTTP servers (such as Apache) often generate self-referential URLs. | HTTP servers, such as Apache, often generate self-referential URLs. | diff --git a/.rulesync/skills/doc-review/guides/conscious-language.md b/.rulesync/skills/doc-review/guides/conscious-language.md new file mode 100644 index 000000000..76bcfb076 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/conscious-language.md @@ -0,0 +1,41 @@ +# Conscious Language + +Format applicability: [All] +Severity: **Must-fix** + +## Rule + +Replace non-inclusive terminology with inclusive alternatives. When possible, rewrite documentation to avoid the problematic terms entirely. Align with your product team's agreed-upon replacements. + +## Blacklist / Whitelist + +| DON'T | DO (preferred) | DO (alternatives) | +|---|---|---| +| blacklist | blocklist | denylist | +| whitelist | allowlist | passlist | + +### Examples + +| DON'T | DO | +|---|---| +| Heat blacklists any servers in the list from receiving updated deployments. | Heat excludes any servers in the list from receiving updated deployments. | +| Add a new rule to whitelist a custom binary. | Add a new rule to allow a custom binary. | + +## Master / Slave + +| DON'T | DO (alternatives) | +|---|---| +| master / slave | primary / secondary | +| master / slave | source / replica | +| master / slave | initiator, requester / responder | +| master / slave | controller, host / device, worker, proxy | +| master / slave | director / performer | +| master / slave | controller / port interface (in networking) | +| master (alone) | primary, main, original | + +### Examples + +| DON'T | DO | +|---|---| +| A Ceph Monitor maintains the master copy of the cluster map. | A Ceph Monitor maintains the primary copy of the cluster map. | +| Copy the public key to the slave node. | Copy the public key to the secondary node. | diff --git a/.rulesync/skills/doc-review/guides/contractions.md b/.rulesync/skills/doc-review/guides/contractions.md new file mode 100644 index 000000000..e5dc315ef --- /dev/null +++ b/.rulesync/skills/doc-review/guides/contractions.md @@ -0,0 +1,20 @@ +# Contractions + +Format applicability: [All] +Severity: **Must-fix** in formal product documentation. **Recommended** in informal content. + +## Rule + +Avoid contractions in product documentation (don't, can't, won't, it's, doesn't, isn't, aren't, you're, they're, we'll). Contractions introduce ambiguity and make translation harder. + +## Exception + +Contractions are acceptable in quick start guides or content using a fairly conversational or more conversational style, as defined by the IBM Style guide. + +## Examples + +| DON'T | DO | +|---|---| +| You can't use this feature without... | You cannot use this feature without... | +| It's configured by default. | It is configured by default. | +| Don't restart the service. | Do not restart the service. | diff --git a/.rulesync/skills/doc-review/guides/future-tense.md b/.rulesync/skills/doc-review/guides/future-tense.md new file mode 100644 index 000000000..2cf92eb92 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/future-tense.md @@ -0,0 +1,28 @@ +# Future Tense + +Format applicability: [All] +IBM Reference: Language and grammar > Verbs > Tense +Severity: **Must-fix** when present tense works. **Recommended** when context is ambiguous. + +## Rule + +Avoid "will", "shall", and "going to". Use present tense unless future tense is genuinely required (describing something that truly happens later in a sequence). + +## Why + +- Present tense is clearer, shorter, and translates better. +- Future tense can be inaccurate if the event occurs in the reader's present. +- Future tense uses auxiliary verbs, increasing complexity and mistranslation risk. + +## Examples + +| DON'T | DO | +|---|---| +| The script will upload the following images. | The script uploads the following images. | +| The shutdown command will call the systemctl utility. | The shutdown command calls the systemctl utility. | + +## Exception + +Future tense is acceptable when present tense does not make sense: + +"Cancel a broker deployment only if you are sure that the broker will never respond." diff --git a/.rulesync/skills/doc-review/guides/incomplete-sentences.md b/.rulesync/skills/doc-review/guides/incomplete-sentences.md new file mode 100644 index 000000000..362d7afcc --- /dev/null +++ b/.rulesync/skills/doc-review/guides/incomplete-sentences.md @@ -0,0 +1,19 @@ +# Incomplete Sentences + +Format applicability: [All] +IBM Reference: Lists > Lead-in wording +Severity: **Must-fix** + +## Rule + +Use **complete sentences** to introduce lists, commands, or examples. Incomplete introductions are ambiguous and difficult to translate. + +The introduction before a colon must be a complete, independent clause. + +## Examples + +| DON'T | DO | +|---|---| +| Examples of this type of interaction include: | The following statements are examples of this type of interaction: | +| Ensure you complete: | Complete the following procedures: | +| To configure: | To configure the service, complete the following steps: | diff --git a/.rulesync/skills/doc-review/guides/inline-links.md b/.rulesync/skills/doc-review/guides/inline-links.md new file mode 100644 index 000000000..3a944be6c --- /dev/null +++ b/.rulesync/skills/doc-review/guides/inline-links.md @@ -0,0 +1,21 @@ +# Inline Links + +Format applicability: [All] +IBM Reference: References +Severity: **Must-fix** for "Click here" and bare URLs. **Recommended** for link placement. + +## Rule + +- Use inline links **sparingly**. +- Provide **context before the link** describing what the user will find. +- Use **"For more information about"**, NOT "For more information on". +- Specify the title of the target topic or section for context. +- Prefer placing links in **Prerequisites** or **Additional resources** sections. +- Never use **"Click here"** or bare URLs as link text. + +## Examples + +| DON'T | DO | +|---|---| +| Click here for more information on Solution Patterns. | For more information about using Solution Patterns, see the Creating cloud-native applications documentation. | +| Refer to Technology Preview at https://access.redhat.com/... | For more information about the support scope, see the Technology Preview documentation. | diff --git a/.rulesync/skills/doc-review/guides/markdown-specific.md b/.rulesync/skills/doc-review/guides/markdown-specific.md new file mode 100644 index 000000000..474801162 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/markdown-specific.md @@ -0,0 +1,137 @@ +# Markdown-Specific Rules + +Format applicability: [Markdown only] + +These rules apply only to `.md` and `.markdown` files. Skip all rules in this guide when reviewing AsciiDoc files. + +## Heading Syntax + +### Rules +- Use ATX-style headings (`#`, `##`, `###`) — not Setext-style (underlines). +- Include a blank line before and after headings. +- Include a space between `#` and heading text. +- Do not skip heading levels (e.g., do not jump from `##` to `####`). +- Use sentence-style capitalization (same as general heading rules). + +| DON'T | DO | +|---|---| +| `#Heading` (no space) | `# Heading` | +| `## My Heading` then `#### Sub` (skipped `###`) | `## My heading` then `### Sub` | + +**Severity**: Must-fix. + +## Bold and Italic Syntax + +### Mapping from general rules +The general style rules reference bold and italic formatting. In Markdown: + +| Style | Markdown syntax | Used for | +|---|---|---| +| Bold | `**text**` | UI element names, emphasis | +| Italic | `*text*` or `_text_` | Introducing new terms, variable values | +| Monospace | `` `text` `` | Commands, code, file names, paths | +| Bold monospace | `` **`text`** `` | N/A — avoid in Markdown | + +**Note**: AsciiDoc uses single `*` for bold, which differs from Markdown. When reviewing Markdown, check that bold uses double asterisks `**`. + +**Severity**: Must-fix for incorrect formatting syntax. + +## Links + +### Inline links +```markdown +[link text](URL) +``` + +### Reference-style links +```markdown +[link text][ref-id] + +[ref-id]: URL "Optional title" +``` + +### Rules +- Always provide descriptive link text — never use "Click here" or bare URLs. +- Use "For more information about", not "For more information on". +- When possible, place links in a dedicated "Additional resources" or "See also" section rather than inline. + +| DON'T | DO | +|---|---| +| `Click [here](url) for more info.` | `For more information about X, see [Title of page](url).` | +| `https://example.com/docs` (bare URL) | `[Product documentation](https://example.com/docs)` | + +**Severity**: Must-fix for "Click here" and bare URLs. Recommended for link placement. + +## Images + +### Syntax +```markdown +![Alt text](path/to/image.png "Optional title") +``` + +### Rules +- Always include descriptive alt text for accessibility. +- Avoid unnecessary screenshots (same as general screen capture rules). +- Use relative paths for images within the same repository. + +**Severity**: Must-fix for missing alt text. Recommended for unnecessary images. + +## Code Blocks + +### Inline code +Use single backticks for command names, file paths, and code references: +```markdown +Run the `ls` command. +``` + +### Fenced code blocks +Use triple backticks with a language identifier: +````markdown +```yaml +key: value +``` +```` + +### Rules +- Always specify a language identifier for fenced code blocks when applicable. +- Use backticks (not indentation) for code blocks. +- Format user-replaceable values in code with angle brackets and describe them: ``. + +**Severity**: Recommended for missing language identifiers. Must-fix for unformatted commands. + +## Lists in Markdown + +### Unordered lists +- Use `-` or `*` consistently (do not mix within a document). +- Include a blank line before the first list item. + +### Ordered lists +- Use `1.` for all items (Markdown auto-numbers) or use explicit numbering. +- For single-step procedures, use an unordered list instead. + +### Nesting +- Indent nested items by 2 or 4 spaces consistently. +- Do not nest beyond 2 levels. + +**Severity**: Recommended for consistency. Must-fix for excessive nesting. + +## Admonitions in Markdown + +Markdown has no native admonition syntax. Common conventions: + +### Blockquote style +```markdown +> **Note:** Additional guidance text here. +``` + +### GitHub-flavored alerts (if supported) +```markdown +> [!NOTE] +> Additional guidance text here. +``` + +### Rules +- When using admonition-like callouts, follow the same rules as AsciiDoc admonitions: keep them short, do not include procedures, and minimize their frequency. +- Use only valid types: Note, Important, Warning, Tip (not Caution). + +**Severity**: Recommended. diff --git a/.rulesync/skills/doc-review/guides/minimalism.md b/.rulesync/skills/doc-review/guides/minimalism.md new file mode 100644 index 000000000..008ba19c8 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/minimalism.md @@ -0,0 +1,113 @@ +# Minimalism + +Format applicability: [All] +Reference: Red Hat Minimalism Guidelines, IBM Style Guide +Severity: **Must-fix** for unclear content. **Recommended** for content that could be shorter. + +## Rule + +Write only what users need to know. Focus on tasks, not features. Remove redundant or obvious information. Use simple, direct language. Get users to their goal quickly. + +## Customer focus and action orientation + +- Content must focus on actions and customer tasks. +- Explain features in terms of what users can do with them, not what they are. +- Content should answer "how do I...?" not "what is...?" +- Separate conceptual and background information from procedural tasks. + +| DON'T | DO | +|---|---| +| The Frobnicator module provides a powerful interface for managing widgets. | You can manage widgets by using the Frobnicator module. | +| This feature enables advanced configuration. | You can configure advanced settings by... | + +## Scannability and findability + +- Content must be easy to scan in a few seconds. +- Use bulleted lists to break up dense paragraphs. +- Use tables for comparative or reference information. +- Headings must describe the content that follows. +- Use short paragraphs and sentences. + +**Flag**: Paragraphs longer than 5-6 sentences that could be broken into a list or shorter paragraphs. + +## Sentences + +- Aim for fewer than **25 words** per sentence. +- Use only required words — every word must earn its place. +- Split long sentences into shorter ones. +- Each sentence must add value. If removing it does not change the user's understanding, remove it. + +**Flag**: Sentences over 25 words that can be split or shortened. + +## Conciseness — removing fluff + +### Self-referential text (remove entirely) + +| DON'T | DO | +|---|---| +| This section describes how to configure the service. | *(Remove and start directly with the content)* | +| This topic explains the architecture of the system. | *(Remove and start directly with the content)* | +| This guide shows you how to install the product. | *(Remove and start directly with the content)* | +| The following paragraphs discuss... | *(Remove and start directly with the content)* | +| As mentioned earlier... | *(Remove or link to the specific section)* | + +### Obvious statements (remove entirely) + +| DON'T | DO | +|---|---| +| As you know, Kubernetes orchestrates containers. | *(Remove — if the reader knows, do not state it)* | +| It is important to note that the service must be running. | The service must be running. | +| It goes without saying that backups are essential. | *(Remove — if it goes without saying, do not say it)* | +| Please note that this command requires root privileges. | This command requires root privileges. | +| Keep in mind that the default timeout is 30 seconds. | The default timeout is 30 seconds. | + +### Redundant phrases (shorten) + +| DON'T | DO | +|---|---| +| in order to | to | +| at this point in time | now | +| due to the fact that | because | +| for the purpose of | to, for | +| in the event that | if | +| has the ability to | can | +| is able to | can | +| make use of | use | +| a large number of | many | +| on a daily basis | daily | +| at the present time | now, currently | +| in spite of the fact that | although | +| with regard to | about | +| in conjunction with | with | +| the majority of | most | +| in close proximity to | near | +| take into consideration | consider | +| it is necessary to | you must | +| give consideration to | consider | +| has the capability to | can | + +### Unnecessary adverbs and modifiers (remove or replace) + +Flag and consider removing these filler words when they do not add meaning: + +- very, really, quite, rather, somewhat +- just, basically, actually, essentially, totally +- obviously, clearly, simply, easily +- specific, particular, certain (when vague) + +## Admonitions, screenshots, and diagrams + +- Use admonitions only when necessary — not for general information that belongs in the main text. +- Use screenshots only when text alone is insufficient. +- Use diagrams only when they add value that text alone cannot provide. + +**Flag**: Excessive admonitions (more than 2-3 per page), screenshots that duplicate text content, diagrams that do not clarify complex relationships. + +## How to evaluate + +For each paragraph, ask: +1. Does this help the user complete their task? +2. Can this be said in fewer words? +3. Would removing this change the user's understanding? + +If the answer to #3 is "no", flag it for removal. diff --git a/.rulesync/skills/doc-review/guides/optional-and-conditional-steps.md b/.rulesync/skills/doc-review/guides/optional-and-conditional-steps.md new file mode 100644 index 000000000..fd8fd5aba --- /dev/null +++ b/.rulesync/skills/doc-review/guides/optional-and-conditional-steps.md @@ -0,0 +1,30 @@ +# Optional and Conditional Steps + +Format applicability: [All] +IBM Reference: Procedures > Indicating optional and conditional steps +Severity: **Must-fix** + +## Rule + +### Optional steps +- Begin with **"Optional:"** (with colon). +- If the optional step has benefits worth emphasizing, format it as a conditional step using "if" or "when". + +### Conditional steps +- Begin with **"If"** or state the constraint first. + +## Examples + +### Optional steps + +| DON'T | DO | +|---|---| +| You can optionally tune the frequency. | Optional: Tune the frequency when you redeploy the overcloud. | +| Reload the systemd daemon. Optionally, verify the new timeout value. | Reload the systemd daemon. Optional: Verify the new timeout value. | + +### Conditional steps + +| DON'T | DO | +|---|---| +| Refresh the page if your Internet connection drops. | If your Internet connection drops before the transfer is complete, refresh the download page. | +| For master repositories: In the IP address field, type the IP address. | Master repository only: In the IP address field, type the IP address. | diff --git a/.rulesync/skills/doc-review/guides/parallelism.md b/.rulesync/skills/doc-review/guides/parallelism.md new file mode 100644 index 000000000..8bc91e774 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/parallelism.md @@ -0,0 +1,22 @@ +# Parallelism + +Format applicability: [All] +IBM Reference: Global audiences +Severity: **Must-fix** + +## Rule + +All list items must follow the **same grammatical structure**: same part of speech, tense, and voice. Parallel lists are easier to read and translate. + +## Examples + +| DON'T | DO | +|---|---| +| Vaccination plan information campaign for employees / Educating employees about its importance / Employees should be notified | Informing employees about the vaccination plan / Educating employees about its importance / Notifying employees about when they can get flu shots | +| Measure the amount of oil. / The new filter should be inserted. / You must inspect the bearings. | Measure the amount of oil. / Insert the new filter. / Inspect the bearings. | + +## How to check + +1. Identify the grammatical form of the first list item (imperative verb, gerund, noun phrase, etc.). +2. Verify every other item uses the same form. +3. Check that tense and voice are consistent across all items. diff --git a/.rulesync/skills/doc-review/guides/passive-voice.md b/.rulesync/skills/doc-review/guides/passive-voice.md new file mode 100644 index 000000000..e57d61233 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/passive-voice.md @@ -0,0 +1,25 @@ +# Passive Voice + +Format applicability: [All] +IBM Reference: Language and grammar > Verbs > Voice +Severity: **Must-fix** in instructions/procedures. **Recommended** in conceptual content. + +## Rule + +Prefer active voice. Active voice focuses on the performer and is clearer, shorter, and more direct. + +Passive voice is acceptable only when: +- The performer of the action is unknown or unimportant. +- You want to avoid blaming the user (e.g., error messages). + +## How to detect + +Look for forms of "to be" + past participle: is deployed, was configured, can be used, should be turned on, are displayed. + +## Examples + +| DON'T | DO | +|---|---| +| The stack can be deployed in multiple scenarios. | You can deploy the stack in multiple scenarios. | +| The Limits window is used to specify the minimum and maximum values. | In the Limits window, specify the minimum and maximum values. | +| The printer should now be turned on. | Turn the printer on. | diff --git a/.rulesync/skills/doc-review/guides/phrasal-verbs.md b/.rulesync/skills/doc-review/guides/phrasal-verbs.md new file mode 100644 index 000000000..dc16dc4fc --- /dev/null +++ b/.rulesync/skills/doc-review/guides/phrasal-verbs.md @@ -0,0 +1,31 @@ +# Phrasal Verbs + +Format applicability: [All] +IBM Reference: Language and grammar > Prepositions +Severity: **Recommended** + +## Rule + +Replace phrasal verbs (verb + preposition) with single-word equivalents. Phrasal verbs cause translation problems and are harder for non-native speakers to interpret. + +## Replacement table + +| DON'T (phrasal verb) | DO (single verb) | +|---|---| +| need to | must | +| speed up | accelerate | +| set up (verb) | configure | +| fill in | complete | +| look at | review, examine | +| make sure | ensure, verify | +| find out | determine, learn | +| carry out | perform, complete | +| go through | review, complete | +| point out | indicate, note | + +## Examples + +| DON'T | DO | +|---|---| +| Set your environment up with the following parameters. | Configure your environment with the following parameters. | +| This process speeds up the initial synchronization. | This process accelerates the initial synchronization. | diff --git a/.rulesync/skills/doc-review/guides/possessives-and-apostrophes.md b/.rulesync/skills/doc-review/guides/possessives-and-apostrophes.md new file mode 100644 index 000000000..cc51fedee --- /dev/null +++ b/.rulesync/skills/doc-review/guides/possessives-and-apostrophes.md @@ -0,0 +1,28 @@ +# Possessives and Apostrophes + +Format applicability: [All] +IBM Reference: Language and grammar > Possessives +Severity: **Must-fix** + +## Rule + +Do NOT use `'s` for possessive forms of: +- Product names +- Brand names +- Abbreviations + +Use `'s` only for possessive forms of people. + +## Examples + +| DON'T | DO | +|---|---| +| the GUI's layout | the GUI layout | +| your overcloud's configuration | your overcloud configuration | +| the computer's keyboard's Alt key | the Alt key on the computer keyboard | +| IBM's Cloud infrastructure | the IBM Cloud infrastructure | +| the object's properties | the object properties | + +## Note + +The IBM Style Guide allows `'s` when it provides the clearest wording. However, reducing possessive `'s` usage increases clarity and improves translation for international audiences. diff --git a/.rulesync/skills/doc-review/guides/screen-captures.md b/.rulesync/skills/doc-review/guides/screen-captures.md new file mode 100644 index 000000000..53a5e1e8a --- /dev/null +++ b/.rulesync/skills/doc-review/guides/screen-captures.md @@ -0,0 +1,20 @@ +# Screen Captures (Screenshots) + +Format applicability: [All] +IBM Reference: Figures > Screen captures +Severity: **Recommended** + +## Rule + +Avoid screen captures in documentation unless text alone is insufficient to add clarity. + +## Problems with screen captures + +- Become out-of-date quickly and require extra maintenance when the UI changes. +- Translation of screen captures is much more difficult than text translations. +- Screen readers cannot interpret screen captures. +- You must use appropriate alt text with screen captures. + +## When reviewing + +Flag any screenshot or image reference that could be replaced with a text description. If screen captures are necessary, verify that appropriate alt text is provided. diff --git a/.rulesync/skills/doc-review/guides/single-step-procedures.md b/.rulesync/skills/doc-review/guides/single-step-procedures.md new file mode 100644 index 000000000..8a1ff87f1 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/single-step-procedures.md @@ -0,0 +1,31 @@ +# Single-Step Procedures + +Format applicability: [All] +Modular Documentation Reference Guide: Section 3.1.2 +Severity: **Must-fix** + +## Rule + +Use a **bullet point** (not a numbered step) for: +- Single-step procedures +- Single prerequisites + +A numbered list with one item looks awkward and implies more steps follow. + +This guideline is a deviation from the IBM Style Guide. + +## Example + +### Correct +**Prerequisites** +- Install the dnf-automatic package. + +**Procedure** +- Run the configuration script. + +### Incorrect +**Prerequisites** +1. Install the dnf-automatic package. + +**Procedure** +1. Run the configuration script. diff --git a/.rulesync/skills/doc-review/guides/titles-and-headings.md b/.rulesync/skills/doc-review/guides/titles-and-headings.md new file mode 100644 index 000000000..2255f7e5f --- /dev/null +++ b/.rulesync/skills/doc-review/guides/titles-and-headings.md @@ -0,0 +1,30 @@ +# Titles and Headings + +Format applicability: [All] +IBM Reference: Structure and Format > Headings +Severity: **Must-fix** for capitalization. **Recommended** for title phrasing. + +## Rule + +Write descriptive titles and headings that help users find information. + +### Information-type conventions +- **Procedure titles**: Use gerunds (-ing form). Example: "Creating a virtual machine template" +- **Concept/reference titles**: Use nouns. Example: "Benefits of bucket policies" + +### Formatting rules +- Use **sentence-style capitalization** (capitalize only the first word and proper nouns). +- Aim for **3-12 words** per title, **50-80 characters** for search optimization. +- Do NOT start with "How to" or vague verbs like "Using" or "Understanding". +- Do NOT end headings with a colon. +- Be goal-oriented: use an active, descriptive verb for procedures. + +## Examples + +| DON'T | DO | +|---|---| +| How to Create a Virtual Machine Template | Creating a virtual machine template | +| Using Bucket Policies | Granting permissions with bucket policies | +| Understanding bucket policies | Benefits of bucket policies | +| Variables to Be Determined by the Program | Variables to be determined by the program | +| Requirements for Linux and UNIX Operating Systems | Requirements for Linux and UNIX operating systems | diff --git a/.rulesync/skills/doc-review/guides/ui-elements.md b/.rulesync/skills/doc-review/guides/ui-elements.md new file mode 100644 index 000000000..d46275271 --- /dev/null +++ b/.rulesync/skills/doc-review/guides/ui-elements.md @@ -0,0 +1,47 @@ +# UI Elements + +Format applicability: [All] +IBM Reference: Technical elements > UI elements +Severity: **Must-fix** for incorrect verb/element pairings and unbold GUI elements. **Recommended** for minor terminology. + +## Rule + +- **Bold** all GUI element names. +- **Match** the capitalization and spelling exactly as shown in the UI. + +## Verbs by element type + +| UI Element | Correct Verbs | Incorrect Verbs | +|---|---|---| +| Checkbox | Select, Clear | Click, Check, Uncheck | +| Drop-down list | Select (item), Click (arrow) | Choose from drop-down | +| Field | Enter | Add, Type in, Write | +| Radio button | Click, Selected (state) | Select, Choose | +| Window | Open, Close | — | +| + / - (expand/collapse) | Expand, Collapse | Click the + symbol | + +## Element naming conventions + +| UI Element | Format | Example | +|---|---|---| +| Checkbox | Label + "checkbox" | Select the **Password protected** checkbox. | +| Drop-down list | "From the [Label] list, select..." | From the **Item** list, select **Desktop**. | +| Field | "In the [Label] field, enter..." | In the **Name** field, enter a name for the new column. | +| Radio button | Use label only | In the **Active Desktop** area, click **Enable web content on my desktop**. | +| Window | Title + "window" | In the **Print** window, click **All**. | + +## Terms to avoid for windows + +| DON'T | DO | +|---|---| +| dialog | window | +| dialog box | window | +| pop-up | window | + +## Examples + +| DON'T | DO | +|---|---| +| When you click New, a dialog box appears. | The **Print** window opens. | +| Click the + symbol. | In the navigation pane, expand **Performance**. | +| In the Name area, add a new name. | In the **Name** field, enter a name. | diff --git a/.rulesync/skills/doc-review/guides/unordered-lists.md b/.rulesync/skills/doc-review/guides/unordered-lists.md new file mode 100644 index 000000000..7aea678cb --- /dev/null +++ b/.rulesync/skills/doc-review/guides/unordered-lists.md @@ -0,0 +1,13 @@ +# Unordered Lists + +Format applicability: [All] +IBM Reference: Structure and format > Lists > Unordered lists +Severity: **Recommended** for ordering/nesting. **Must-fix** for inconsistent sentence structure. + +## Rule + +- Use bulleted lists when sequence does not matter. +- Arrange items logically or alphabetically when there is no natural ordering. +- **Do not nest** beyond 2 levels. Never nest more than 3 levels — restructure instead. +- All items must be **consistently** complete sentences or fragments, not mixed. +- If items are complete sentences, end each with a period. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..ff144139c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,188 @@ +# AGENTS.md + +This file helps AI agents understand the structure, tooling, and conventions of the +Validated Patterns documentation repository so they can make correct, buildable changes. + +## Project Overview + +This is the documentation site for [validatedpatterns.io](https://validatedpatterns.io), +built with **Hugo** (static site generator) and the **PatternFly** theme. Content is +authored in both **AsciiDoc** (rendered by Asciidoctor with Rouge syntax highlighting) and +**Markdown** (rendered by Goldmark). There is no JavaScript framework, no TypeScript, and +no `package.json` at the repository root. + +## Repository Layout + +``` +content/ Site content organized by section (blog/, ci/, contribute/, learn/, patterns/, search/) +modules/ Reusable AsciiDoc modules and pattern metadata (included via include::) +layouts/ Hugo templates, partials (layouts/partials/), and shortcodes (layouts/shortcodes/) +archetypes/ Hugo content scaffolds for new pages (blog, learn, contribute, pattern) +themes/patternfly/ Vendored PatternFly theme — do NOT edit +static/ Static assets (CSS, JS, images, videos) +assets/ Hugo asset pipeline (images) +utils/ Ruby scripts (e.g. flatten_yaml.rb for pattern metadata) +config.yaml Main Hugo configuration +Makefile Build, serve, and test commands +``` + +## Building and Serving Locally + +All build commands use Podman to run a container with Hugo and Asciidoctor pre-installed. + +| Command | Purpose | +|---|---| +| `make serve` | Build and serve locally at http://localhost:4000 (preferred) | +| `make build` | Build the site into `public/` | +| `make test` | Build and run link checking (htmltest) | +| `make clean` | Remove generated files | + +The container image is `quay.io/validatedpatterns/homepage-container:main`. + +Alternatively, install Hugo and Asciidoctor locally and run `hugo server` (serves at +http://localhost:1313). + +## Content Authoring Conventions + +### Formats + +Both `.adoc` (AsciiDoc) and `.md` (Markdown) files are used throughout the site. Either +format is acceptable for new content. When editing existing content, match the format +already used in that section. + +- AsciiDoc is predominant in `learn/`, `contribute/`, and `modules/`. +- Markdown is common in `patterns/` and `blog/`. + +### Frontmatter + +All content files use YAML frontmatter between `---` delimiters. Fields vary by section: + +**Patterns** (`content/patterns//_index.md` or `_index.adoc`): + +```yaml +--- +title: Pattern Name +date: 2025-10-24 +summary: Short description of the pattern +tier: sandbox # sandbox | tested | maintained +rh_products: + - Red Hat OpenShift Container Platform +industries: + - General +partners: + - Partner Name +links: + install: getting-started + bugs: https://github.com/... + feedback: https://docs.google.com/... +--- +``` + +**Blog** (`content/blog/`): + +```yaml +--- +title: Blog Post Title +date: 2024-07-12 +summary: Short description +author: Author Name +blog_tags: + - patterns + - git +--- +``` + +**Learn / Contribute**: + +```yaml +--- +title: Page Title +layout: default +menu: learn +weight: 10 +--- +``` + +### Naming Conventions + +- **Index pages**: Must be `_index.md` or `_index.adoc`. +- **File names**: Lowercase, dash-separated (e.g. `getting-started.adoc`, `cluster-sizing.md`). +- **Directory names**: Lowercase, dash-separated (e.g. `multicloud-gitops`, `rag-llm-cpu`). + +### Markdown Conventions + +- Standard Goldmark-rendered Markdown (Hugo's default). +- Use Hugo shortcodes for alerts and UI elements (see Hugo Shortcodes below). +- Use fenced code blocks with language identifiers (e.g. ` ```yaml `, ` ```bash `). +- Raw HTML is technically allowed (unsafe Goldmark rendering is enabled) but discouraged. + +### AsciiDoc Conventions + +- Every `.adoc` file should declare a `:_content-type:` attribute: `ASSEMBLY`, `CONCEPT`, + `PROCEDURE`, or `REFERENCE` (per Red Hat modular documentation conventions). +- Reuse content via `include::modules/.adoc[leveloffset=+1]`. +- Use `[source,terminal]` for shell commands and `[source,yaml]`, `[source,go]`, etc. for + code blocks. +- Shared attributes (product names, abbreviations) are defined in + `modules/comm-attributes.adoc`. Use these instead of hard-coding brand names. + +### Hugo Shortcodes + +These shortcodes are available in both `.md` and `.adoc` files (defined in +`layouts/shortcodes/`): + +| Shortcode | Purpose | +|---|---| +| `note` | Info alert box (accepts `title` param and body content) | +| `warning` | Warning alert box | +| `danger` | Danger alert box | +| `button` | Link button (`text`, `url`, `color-class` params) | +| `iframe` | Embedded iframe | +| `rawhtml` | Raw HTML pass-through | + +### Archetypes + +Use `hugo new` with archetypes in `archetypes/` to scaffold new content (blog posts, +learn pages, contribute pages, or full pattern page sets). + +## Writing Style Guidelines + +See `modules/doc-guidelines.adoc` for the full documentation style guide. + +- Follow the [Red Hat Supplementary Style Guide](https://redhat-documentation.github.io/supplementary-style-guide/ssg.md) and [IBM Style](https://www.ibm.com/docs/en/ibm-style). +- Use present tense, active voice, and second person ("you"). +- Sentence-style capitalization in titles and headings. +- Use gerund-form headings for procedures ("Creating", "Managing", "Using"). +- Use noun phrases for non-procedure headings. +- Use **bold** for clickable UI elements. +- Use `monospace` for code, file paths, IP addresses, ports, HTTP verbs, and status codes. + +## Quality Checks + +| Check | Command | Config | +|---|---|---| +| Link checking | `make htmltest` | `.htmltest.yml` | +| Spellcheck | `make spellcheck` | `.spellcheck.yml`, `.wordlist.txt` | +| Super-Linter | `make super-linter` | `.github/workflows/superlinter.yml` | +| Secret scanning | (runs in CI) | `.github/linters/.gitleaks.toml` | +| Prose linting (Vale) | (runs in CI on PRs) | `utils/vale-pr-comments.sh` | + +When adding new technical terms that fail spellcheck, add them to `.wordlist.txt` (sorted, +lowercase, no duplicates). Run `make lintwordlist` to normalize the file. + +## CI/CD Workflows + +| Workflow | File | Trigger | +|---|---|---| +| Deploy to GitHub Pages | `.github/workflows/gh-pages.yml` | Push to `main` | +| Super-Linter | `.github/workflows/superlinter.yml` | Push and pull request | +| Link checking | `.github/workflows/htmltest.yml` | Scheduled daily | +| Pattern metadata sync | `.github/workflows/metadata-docs.yml` | workflow_call from pattern repos | + +## Things to Avoid + +- Do **not** edit files under `themes/patternfly/` (vendored theme). +- Do **not** edit or commit files under `public/` (generated build output, gitignored). +- Do **not** commit `.vale.ini` or `.vale/` (gitignored, local-only config). +- Do **not** hard-code brand or product names that are already defined as attributes in + `modules/comm-attributes.adoc`; use the AsciiDoc attributes instead. diff --git a/README.md b/README.md index a96caef6c..a34e4d538 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,6 @@ You can install Hugo on different platforms (Linux, Windows, macOS) using a numb You can install Asciidoctor on different platforms (Linux, Windows, macOS) using a number of methods. For more information on how to install Asciidoctor on your desired platform, see [Install Asciidoctor](https://asciidoctor.org/#installation). - ## Deploy the website locally using Hugo You can run Hugo as a local server to test out the site. @@ -28,3 +27,39 @@ You can run Hugo as a local server to test out the site. $ hugo server 4. View the site on your browser at [`http://localhost:1313/`](http://localhost:1313/). + +## AI tooling + +### AGENTS.md + +This repository includes an [AGENTS.md](AGENTS.md) file that helps AI agents understand the structure, tooling, and conventions of the repository so they can make correct, buildable changes. It covers the repository layout, build commands, content authoring conventions, frontmatter schemas, and style guidelines. + +### AI documentation skills + +The repository also includes AI agent skills for creating and reviewing documentation, located in `.rulesync/skills/`. These skills are synced to your editor using [rulesync](https://www.npmjs.com/package/rulesync). + +#### Available skills + +- **doc-create** -- Create new learn pages or pattern page sets with correct structure and style-compliant content. +- **doc-review** -- Review existing documentation files against 24 Red Hat/IBM style guide rules, with format-aware checking for AsciiDoc and Markdown. + +#### Prerequisites for installing AI skiils + +- [Node.js](https://nodejs.org/) and npm +- [rulesync](https://www.npmjs.com/package/rulesync) installed globally: + + $ npm install -g rulesync + +#### Generating skills for your editor + +To sync the skills to Cursor: + + $ rulesync generate --targets cursor --features skills + +To sync the skills to Claude Code: + + $ rulesync generate --targets claudecode --features skills + +To sync to both at once: + + $ rulesync generate --targets cursor claudecode --features skills diff --git a/rulesync.jsonc b/rulesync.jsonc new file mode 100644 index 000000000..2011a5c98 --- /dev/null +++ b/rulesync.jsonc @@ -0,0 +1,27 @@ +{ + "targets": [ + "copilot", + "cursor", + "claudecode", + "codexcli" + ], + "features": [ + "rules", + "ignore", + "mcp", + "commands", + "subagents", + "skills", + "hooks" + ], + "baseDirs": [ + "." + ], + "delete": true, + "verbose": false, + "silent": false, + "global": false, + "simulateCommands": false, + "simulateSubagents": false, + "simulateSkills": false +} \ No newline at end of file