Add style guide and improve skills by dbreseman · Pull Request #11032 · mendix/docs

dbreseman · 2026-04-17T09:15:05Z

Adds Mendix style guide documentation and updates Claude Code configuration to use it.

Adds style guide pages under content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/:
- grammar-formatting.md — Grammar and formatting rules
- terminology.md — General terminology guidance with capitalization and hyphenation rules
- product-naming-guide.md — Mendix product names and terms reference
Updates CLAUDE.md to reference the style guides
Refines polish and proofread skills
- Simplifies the proofread skill to better differentiate it from polish, which applies the style guide
- Speeds up the polish skill and gets it to apply the in-repo style guidance

These changes create a single source of truth for documentation style decisions and enable more consistent automated editing.

github-actions · 2026-04-17T09:31:26Z

⚠️ Claude Configuration Warning

You've modified Claude Code configuration files. These files contain the shared configuration for all contributors. Please revert this change if unintended. ONLY modify these files if you need to change shared configurations that apply to everyone and have discussed this change with the TW team.

To override the Claude settings locally, use .claude/settings.local.json instead. This local file is gitignored and overrides the repo default.

For example, if you're changing AWS_PROFILE:
The default profile name is my-sandbox. If your AWS profile has a different name, override it locally instead of changing the shared file.

Create or edit .claude/settings.local.json in the repo root and include the following lines:

{
  "env": {
    "AWS_PROFILE": "your-sandbox-name"
  }
}

MarkvanMents

Looks good.
I have a couple of comments, but nothing that would stop us merging.

MarkvanMents · 2026-04-17T11:55:11Z

 ---
 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 clarity, make more readable, or clean up documentation while preserving its structure.
+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 clarity, make more readable, check style guide compliance, improve language, or clean up documentation while preserving its structure.


I wonder whether the order of these matters?

I would probably put "improve clarity" and "improve language" next to each other. Or just say "improve the document"?

MarkvanMents · 2026-04-17T11:58:22Z

 **Polish should**:
+* Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/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)


Do we expect Claude to be able to read and understand the images.

Do we need an image-reading skill to help find the image and know what to say about it?

It doesn't actually look at the images, but rather infers based on context what the image probably shows. This tends to be reasonably accurate but it definitely isn't perfect. My feeling is that this is better overall than omitting the alt text parameter, but happy to discuss! Claude has the path to the image, and it can read and analyze the images if directed to—I'm just hesitant to require that as part of this skill because it will make it a fair bit slower and more expensive. It would be a good project for someone to take up though, if someone is interested in making and testing a separate skill (or incorporating it into the in-development accessibility one) with robust alt-text guidelines.

MarkvanMents · 2026-04-17T12:51:34Z

-Then immediately continue: improve clarity and readability without changing meaning, structure, or paragraph order:
+Improve clarity and readability without changing meaning, structure, or paragraph order:

 **Polish should**:


Do we need to say not to worry about checking links. Claude seemed very worried about links, but we have htmltest for that which is more reliable and works on the built site.

I personally find it helpful if Claude keeps an eye out for misformatted link references, and I haven't run into situations where it wastes a lot of time on it. Maybe it's more of an issue if you're looking at multiple pages at once or if you mention links specifically? Let's talk about this more.

MarkvanMents · 2026-04-17T12:53:28Z

+Priority order for determining scope:
+1. If the user has selected text in a file (check for `ide_selection` tags), only polish the selected text in that file. Don't polish the entire document.
+2. If there's one open file (check for `ide_opened_file` tags) and no selection, work on the entire file.
+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.


Nice - hope it works consistently 🙂

It isn't perfect but it seemed to help a bit. It finds the context a lot better with natural language, like "proofread this file".

MarkvanMents · 2026-04-17T12:55:33Z

@@ -1,18 +1,17 @@
 ---
 name: proofread


Does the style guide not help with proofreading? For example, picking up titles which are not gerunds?

I think of those as different things—my intent is to have the proofreading skill catch situations where the language is wrong in any context, and those mistakes are clear whether or not the reader is familiar with our style. Then the polish skill focuses on things where the text is wrong because it doesn't match our specific style guidance (voice, tone, formatting, punctuation, terminology, etc). Maybe it's worth reconsidering these skill names to make it more intuitive to understand what they do?

MarkvanMents · 2026-04-17T12:57:57Z

@@ -0,0 +1,553 @@
+---
+title: "Grammar & Formatting"


I won't review this now. I guess that was a substantial part of what the team did over the past couple of days.

Perhaps I'll do some more investigation and run some tests once it is part of our workflow?

We did spend a fair bit of time discussing it, but that is not reflected here—this is almost an exact copy of what we have on Confluence (changes are mostly just to reformat it for this context: c7cd89c).
I do think carrying on the work of style guide review/simplification/clarification is an important next step for improving AI output and human comprehension, and so far I'm finding that Olu's app and other AI tools are good ways to identify where the style guide could be clearer.

MarkvanMents · 2026-04-17T12:59:23Z

+
+These are branded Mendix product names. However, they do not always need "Mendix" in front of them in the documentation.
+
+### Apps


Do we need to mention that this is only about the Apps part of the Mendix portal. It isn't to be applied whenever the word "app" is used in the plural?

perhaps cross reference term later on

MarkvanMents · 2026-04-17T13:34:27Z

 ## Style Standards

-* **Guiding manual** – Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Apply grammar, inclusive language, terminology, and formatting rules from that document.
+* **Guiding manual** – Mendix-specific style guides (see subsection below) extend and customize the Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Consult the Mendix style guides first for grammar, inclusive language, terminology, and formatting rules; use MSG as fallback for topics not covered by Mendix guides.


Do we need to tie MSG to "Microsoft Style Guide" somehow to ensure Claude understands they are the same thing?

Nope! It doesn't seem to have any trouble with the acronym, but let me know if you see a case where it gets confused. Per Claude:

Co-authored-by: Mark van Ments <35492184+MarkvanMents@users.noreply.github.com>

github-actions · 2026-04-17T13:51:10Z

⚠️ Claude Configuration Warning

You've modified Claude Code configuration files. These files contain the shared configuration for all contributors. Please revert this change if unintended. ONLY modify these files if you need to change shared configurations that apply to everyone and have discussed this change with the TW team.

To override the Claude settings locally, use .claude/settings.local.json instead. This local file is gitignored and overrides the repo default.

For example, if you're changing AWS_PROFILE:
The default profile name is my-sandbox. If your AWS profile has a different name, override it locally instead of changing the shared file.

Create or edit .claude/settings.local.json in the repo root and include the following lines:

{
  "env": {
    "AWS_PROFILE": "your-sandbox-name"
  }
}

github-actions · 2026-04-17T14:12:02Z

⚠️ Claude Configuration Warning

You've modified Claude Code configuration files. These files contain the shared configuration for all contributors. Please revert this change if unintended. ONLY modify these files if you need to change shared configurations that apply to everyone and have discussed this change with the TW team.

To override the Claude settings locally, use .claude/settings.local.json instead. This local file is gitignored and overrides the repo default.

For example, if you're changing AWS_PROFILE:
The default profile name is my-sandbox. If your AWS profile has a different name, override it locally instead of changing the shared file.

Create or edit .claude/settings.local.json in the repo root and include the following lines:

{
  "env": {
    "AWS_PROFILE": "your-sandbox-name"
  }
}

dbreseman added 3 commits April 17, 2026 11:14

Add style guide

981e8a7

Tweak style guide files

c7cd89c

Update skills and Claude.md

e427a24

dbreseman self-assigned this Apr 17, 2026

dbreseman marked this pull request as ready for review April 17, 2026 09:32

MarkvanMents approved these changes Apr 17, 2026

View reviewed changes

Update .claude/skills/polish/SKILL.md

b64b4a9

Co-authored-by: Mark van Ments <35492184+MarkvanMents@users.noreply.github.com>

Apply feedback from review

79778fb

dbreseman merged commit c950792 into development Apr 17, 2026
1 of 2 checks passed


		These are branded Mendix product names. However, they do not always need "Mendix" in front of them in the documentation.

		### Apps

Conversation

dbreseman commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 17, 2026

Uh oh!

MarkvanMents left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 17, 2026

Uh oh!

github-actions bot commented Apr 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dbreseman commented Apr 17, 2026 •

edited

Loading