diff --git a/.claude/scripts/README.md b/.claude/scripts/README.md new file mode 100644 index 00000000000..66d4c1e58cc --- /dev/null +++ b/.claude/scripts/README.md @@ -0,0 +1,38 @@ +# Claude Helper Scripts + +Utility scripts to support Claude Code when working with this documentation repository. + +## resolve-doc-url.sh + +Resolves a documentation URL to its source markdown file. + +### Usage + +```bash +.claude/scripts/resolve-doc-url.sh "/path/to/page/" +``` + +### Examples + +```bash +# Find the file for a specific URL +.claude/scripts/resolve-doc-url.sh "/community-tools/contribute-to-mendix-docs/" +# Output: content/en/docs/community-tools/contribute-to-mendix-docs/_index.md + +# Check if a URL exists +.claude/scripts/resolve-doc-url.sh "/some/page/" +# Exit code 0 if found, 1 if not found +``` + +### Benefits + +- **Fast**: Uses grep optimized for file-only output +- **Token-efficient**: Returns only the file path, no surrounding context +- **Reliable**: Matches exact URL in front matter using fixed-string search + +### When to Use + +- Following cross-references between documentation pages +- Validating internal links +- Finding files by their published URL +- Checking if a URL is already in use diff --git a/.claude/scripts/resolve-doc-url.sh b/.claude/scripts/resolve-doc-url.sh new file mode 100644 index 00000000000..4af6c42229e --- /dev/null +++ b/.claude/scripts/resolve-doc-url.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# Resolve a documentation URL to its source markdown file +# Usage: resolve-doc-url.sh "/path/to/page/" + +if [ -z "$1" ]; then + echo "Usage: resolve-doc-url.sh " + echo "Example: resolve-doc-url.sh '/community-tools/contribute-to-mendix-docs/'" + exit 1 +fi + +# Search for the URL in front matter +# Using grep with -l (files only) and -F (fixed string) for speed +grep -rl --include="*.md" "^url: $1$" content/en/docs/ + +# Exit code 0 if found, 1 if not found diff --git a/.claude/skills/add/SKILL.md b/.claude/skills/docs-add/SKILL.md similarity index 55% rename from .claude/skills/add/SKILL.md rename to .claude/skills/docs-add/SKILL.md index 7633d577068..8a45edad32c 100644 --- a/.claude/skills/add/SKILL.md +++ b/.claude/skills/docs-add/SKILL.md @@ -1,11 +1,11 @@ --- -name: add -description: Adds new content to existing documentation pages while preserving the original structure and meaning. Integrates new sections, paragraphs, or information smoothly with appropriate transitions. Use when the user wants to add, insert, include, or append new content to existing pages without rewriting what's already there. +name: docs-add +description: Adds new content to a single documentation page while preserving the original structure and meaning. Integrates new sections, paragraphs, or information smoothly with appropriate transitions. Use when the user wants to add, insert, include, or append new content to existing pages without rewriting what's already there. user-invocable: true disable-model-invocation: true --- -> **After adding content:** Consider running `/polish` to improve clarity or `/proofread` to check for errors in the final result. +> **After adding content:** Consider running `/docs-polish` to improve clarity or `/docs-proofread` to check for errors in the final result. Ask the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content. diff --git a/.claude/skills/enhance/SKILL.md b/.claude/skills/docs-enhance/SKILL.md similarity index 55% rename from .claude/skills/enhance/SKILL.md rename to .claude/skills/docs-enhance/SKILL.md index acd2b06d63a..bf6f395acf8 100644 --- a/.claude/skills/enhance/SKILL.md +++ b/.claude/skills/docs-enhance/SKILL.md @@ -1,10 +1,10 @@ --- -name: enhance -description: Performs comprehensive editing including reorganization, restructuring, and rephrasing while preserving original meaning and intent. Improves flow, strengthens weak phrasing, and enhances overall quality. Use when documentation needs significant structural improvements, better organization, or when the user mentions reorganize, restructure, rewrite, or enhance. +name: docs-enhance +description: Comprehensively edits a single documentation page including reorganization, restructuring, and rephrasing while preserving original meaning and intent. Improves flow, strengthens weak phrasing, and enhances overall quality. Use when documentation needs significant structural improvements, better organization, or when the user mentions reorganize, restructure, rewrite, or enhance. user-invocable: true disable-model-invocation: true --- -> **Skill progression:** This is the most intensive editing. If restructuring isn't needed, use `/polish` for clarity improvements or `/proofread` for basic fixes. +> **Skill progression:** This is the most intensive editing. If restructuring isn't needed, use `/docs-polish` for clarity improvements or `/docs-proofread` for basic fixes. Perform holistic improvements, including reorganization and stronger phrasing, while preserving original intent. This goes beyond basic proofreading and polishing to enhance the overall quality and impact of the text. Consider restructuring sentences, paragraphs, or sections for better flow, replacing weak words with stronger alternatives, and improving clarity and consistency while maintaining the original meaning. However, avoid making changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/docs-polish/SKILL.md similarity index 71% rename from .claude/skills/polish/SKILL.md rename to .claude/skills/docs-polish/SKILL.md index 77d8a460458..e1caba5f525 100644 --- a/.claude/skills/polish/SKILL.md +++ b/.claude/skills/docs-polish/SKILL.md @@ -1,15 +1,15 @@ --- -name: polish -description: Proofreads documentation and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve language and clarity, make more readable, check style guide compliance, or clean up documentation while preserving its structure. +name: docs-polish +description: Proofreads a single documentation page and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve language and clarity, make more readable, check style guide compliance, or clean up documentation while preserving its structure. user-invocable: true disable-model-invocation: false --- -> **Skill progression:** This does everything `/proofread` does plus clarity improvements and style guide enforcement. If only grammar and spelling fixes are needed, use `/proofread`. For deeper reorganization, suggest `/enhance`. +> **Skill progression:** This does everything `/docs-proofread` does plus clarity improvements and style guide enforcement. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`. Improve clarity and readability without changing meaning, structure, or paragraph order: -**Polish should**: +**docs-polish should**: * Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/` * Fix all spelling, grammar, and punctuation errors * Add missing alt text to images (use simple, factual descriptions) @@ -24,8 +24,8 @@ Improve clarity and readability without changing meaning, structure, or paragrap * Apply Mendix style guide standards (overrides the Microsoft Writing Style Guide) * Apply Microsoft Writing Style Guide standards, unless they conflict with the Mendix style guide standards -**Polish should NOT**: -* Move paragraphs or restructure sections (that's `/enhance`) +**docs-polish should NOT**: +* Move paragraphs or restructure sections (that's `/docs-enhance`) * Change technical meaning or accuracy * Significantly increase document length * Change command syntax, code identifiers, variable names, placeholders, or any other text that appears in code formatting (inline backticks or code blocks). Code-formatted text represents literal technical content that must remain unchanged. If you notice an issue with code-formatted text, flag it in the chat but don't edit it directly. diff --git a/.claude/skills/docs-pr-review/SKILL.md b/.claude/skills/docs-pr-review/SKILL.md new file mode 100644 index 00000000000..90a0bbcee7b --- /dev/null +++ b/.claude/skills/docs-pr-review/SKILL.md @@ -0,0 +1,16 @@ +--- +name: docs-pr-review +description: Analyzes all changes in a pull request and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a pull request, or when they want suggestions before making changes. +user-invocable: true +disable-model-invocation: false +--- + +Compare changes between the current branch and the base branch (typically `development`). Read the complete final state of each modified file, not just the diff, to ensure changes don't introduce inconsistencies with unchanged content. + +Analyze all the changes in the current pull request or branch and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Read the whole of each document modified in the pull request to ensure the changes do not make inconsistencies. + +Follow links to other documents in the repo to check for inconsistencies if they seem to provide important related information. + +Do not worry about possible invalid internal links to anchors in the repo as these will be picked up by a separate testing tool after the site has been built. + +Make no edits. diff --git a/.claude/skills/proofread/SKILL.md b/.claude/skills/docs-proofread/SKILL.md similarity index 69% rename from .claude/skills/proofread/SKILL.md rename to .claude/skills/docs-proofread/SKILL.md index 6cf2ca0cfec..7f0f97a384d 100644 --- a/.claude/skills/proofread/SKILL.md +++ b/.claude/skills/docs-proofread/SKILL.md @@ -1,11 +1,11 @@ --- -name: proofread -description: Checks and fixes spelling, grammar, punctuation, basic Markdown formatting, and required front matter fields. Makes minimal corrections without rewording or restructuring. Use when the user asks to proofread, check for spelling and grammar errors, or fix typos. +name: docs-proofread +description: Checks a single documentation page and fixes spelling, grammar, punctuation, basic Markdown formatting, and required front matter fields. Makes minimal corrections without rewording or restructuring. Use when the user asks to proofread, check for spelling and grammar errors, or fix typos. user-invocable: true disable-model-invocation: false --- -> **Skill progression:** This is the lightest touch. If more clarity and style guide work is needed, suggest `/polish`. For deeper restructuring, suggest `/enhance`. +> **Skill progression:** This is the lightest touch. If more clarity and style guide work is needed, suggest `/docs-polish`. For deeper restructuring, suggest `/docs-enhance`. Do NOT rewrite, rephrase, or improve clarity. Proofread only: @@ -29,4 +29,4 @@ Priority order for determining scope: 3. If there are multiple open files, list them and ask which to process. 4. If no files are open, ask for a file path. -If you notice style or clarity issues that need improvement, finish proofreading first, then suggest the user run `/polish` for those improvements. +If you notice style or clarity issues that need improvement, finish proofreading first, then suggest that the user run `/docs-polish` for those improvements. diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md new file mode 100644 index 00000000000..b8986ed2659 --- /dev/null +++ b/.claude/skills/docs-review/SKILL.md @@ -0,0 +1,8 @@ +--- +name: docs-review +description: Analyzes a single documentation page and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on a documentation page or section, or when they want suggestions before making changes. +user-invocable: true +disable-model-invocation: false +--- + +Analyze the page and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Make no edits. diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md deleted file mode 100644 index d4987342485..00000000000 --- a/.claude/skills/review/SKILL.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -name: review -description: Analyzes documentation pages and generates suggestions for improvements, clarifications, inconsistencies, and structural changes without making any edits. Use when the user asks to review, analyze, audit, or provide feedback on documentation, or when they want suggestions before making changes. -user-invocable: true -disable-model-invocation: false ---- - -Analyze the page and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Make no edits. diff --git a/CLAUDE.md b/CLAUDE.md index c40b545f277..acd302592d0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,9 +110,14 @@ Call tools in parallel for independent operations (reading multiple files, multi * **Glob** – Use to find files by pattern (e.g., `*.md`, `**/*config*`) * **Grep** – Use to search file contents for specific text or patterns * **Write** – Use only for creating new files (prefer Edit for existing files) +* **Helper Scripts** – Use `.claude/scripts/resolve-doc-url.sh` to resolve documentation URLs (e.g., `/path/to/page/`) to their source markdown files. This is faster and more token-efficient than using Grep to search front matter. ### Cross-Reference Verification +When following or verifying documentation links: +* Use `.claude/scripts/resolve-doc-url.sh "/path/to/page/"` to quickly find the source file for a URL +* This is more efficient than Grep for URL-to-file lookups + When modifying URLs or anchor IDs: 1. Use Grep to search for the old URL/anchor across all documentation files 2. Identify all references that need updating diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md index 1641d6d1441..aa3891b6b1d 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md @@ -24,7 +24,7 @@ A term may not already be included in this guide for the following reasons: * The term is outdated (meaning, usage of it has been decided against) * The term should not be used in customer-facing resources -This is a useful guide to reference when communicating about the Mendix Platform and especially when you want to [contribute to the Mendix documentation](/developerportal/community-tools/contribute-to-the-mendix-documentation). +This is a useful guide to reference when communicating about the Mendix Platform and especially when you want to [contribute to the Mendix documentation](/community-tools/contribute-to-mendix-docs/). This guide does not give insights into the product roadmap or internal company operations. @@ -153,7 +153,7 @@ Do not use "starter app." ### App User -For a definition of this term, see the [Access Management](/developerportal/collaborate/general-settings/#managing-app-users) section of the *Developer Portal Guide*. +For a definition of this term, see [Access Management](/developerportal/portfolio-management/access-management/). Capitalize in all instances. @@ -431,7 +431,7 @@ This is a generic term, so do not capitalize. ### Product Owner -Capitalize in all instances of the [team role](/developerportal/collaborate/app-roles/#team-roles). +Capitalize in all instances of the [team role](/developerportal/general/app-roles/#team-roles). ### production, acceptance, and test environments diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md index 1e52a332a1f..e0a19ca333e 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md @@ -59,7 +59,7 @@ In the context of development and project management, sometimes using "project" ## app owner -This is not a formalized/Mendix term (in comparison to [App Contact](/developerportal/company-app-roles/#app-contact)), so we cannot assume the user knows what this is. This should be defined in general terms and made clearer via context (for example, via the "Copyright" example in the [MindSphere module documentation](/partners/siemens/mindsphere-module-details#3-1-configuring-the-os-bar)) that it is the user's responsibility to define/interpret what an app owner is for their app. +This is not a formalized/Mendix term (in comparison to [App Contact](/developerportal/general/app-roles/)), so we cannot assume the user knows what this is. This should be defined in general terms and made clearer via context (for example, via the "Copyright" example in the [Insights Hub module documentation](/partners/siemens/mindsphere-module-details/#configuring-the-os-bar)) that it is the user's responsibility to define/interpret what an app owner is for their app. ## article, document, page diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md index e5957de33d5..5a3bd95464c 100644 --- a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md @@ -50,11 +50,12 @@ Do not modify `.claude/settings.json` or other files in the `.claude/` directory This repository includes custom Claude Code skills optimized for documentation work: -* `/proofread` - Checks spelling, grammar, punctuation, and basic Markdown formatting -* `/polish` - Improves clarity, readability, and word choice without changing meaning -* `/enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing -* `/review` - Analyzes documentation and generates suggestions for improvements -* `/add` - Adds new content to an existing page while preserving original structure +* `/docs-proofread` - Checks spelling, grammar, punctuation, and basic Markdown formatting +* `/docs-polish` - Improves clarity, readability, and word choice without changing meaning +* `/docs-enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing +* `/docs-review` - Analyzes documentation and generates suggestions for improvements +* `/docs-add` - Adds new content to an existing page while preserving original structure +* `/docs-pr-review` - Reviews all changes in the PR rather than just a single document These skills are available to all contributors using Claude Code with this repository.