Clarify style guide rules for person, dates, and terminology (#11267)

* Update guidance

* Specify first-person plural guidance for Claude

Author: dbreseman

.claude/skills/docs-polish/SKILL.md

@@ -20,7 +20,8 @@ Improve clarity and readability without changing meaning, structure, or paragrap
 * Simplify wordy or awkward phrasing
 * Improve word choice (more precise or accessible terms)
 * Change passive voice to active voice where appropriate
-* Remove bold and italics used for emphasis (reword or use alerts if needed)
+* Remove first-person plural (we, us, our, let's), except in release notes
+* Remove bold and italics used for emphasis (reword or use alert shortcodes if needed)
 * 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
 

.claude/skills/docs-proofread/SKILL.md

@@ -22,6 +22,7 @@ Do NOT:
 * Change passive voice to active voice
 * Simplify complex sentences
 * Reorganize content
+* Remove Markdown comments
 
 Priority order for determining scope:
 1. If the user has selected text in a file (check for `ide_selection` tags), only proofread the selected text in that file. Don't proofread the entire document.

CLAUDE.md

@@ -76,6 +76,7 @@ Before creating a new file, use Glob to explore the directory structure and unde
 
 * **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.
 * **Tone** – Clear, concise, active voice; use imperative mood for procedures; second person (you/your) when addressing readers. Keep a conversational, straightforward tone. Present tense. Use American English and write for a global audience. Prefer short, everyday words; avoid or explain jargon. Keep it simple—short sentences and fragments are easier to scan and read, and prune excess words. Avoid marketing language.
+* **Person** – Avoid first-person plural (we, us, our, let's) in all documentation except release notes.
 * **Terminology** – Capitalize product names (Mendix, Studio Pro, Developer Portal); use "microflow", "nanoflow", etc. consistently. Never use e.g. or i.e.
 * **Text formatting** – Reserve bold for UI labels, button names, menu items, or other interface text, or for introductions in list items. Don't use italics except to refer to titles and sections. Use wording or alert shortcodes for emphasis; don't use text formatting for emphasis. Use code font only to wrap literal code, filenames, paths, or command-line input. Use `<kbd>` for keyboard shortcuts.
 * **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numerals.

content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting.md

@@ -193,7 +193,7 @@ To insert an em dash, use the keyboard shortcut <kbd>Alt</kbd> + <kbd>0151</kbd>
 
 Write dates in the format **month day, year**, where:
 
-* Month is the full month or a three-letter abbreviation
+* Month is the full month name
 * [Day is the cardinal number](#numbers) (16), not the ordinal number (16th)
 * Year is four digits
 
@@ -461,11 +461,21 @@ Do not use ordinal numbers for dates (see [Dates](#dates)).
 
 ## Person
 
-Address the reader of your documents using the second person instead of the first person: use "you" or "your" instead of "we", "our", or "us".
+Use imperative mood for instructions and second person (you, your) to address the reader. Use "you" instead of "user", or use "end-user" when referring to the user of a Mendix app built on the Mendix Platform.
 
-Assume your reader is the person doing the tasks that you are documenting. Use "you" instead of "user", or use "end-user" when referring to the user of a Mendix app built on the Mendix Platform.
+Avoid first-person plural (we, us, our, let's) in all documentation except release notes.
 
-Always use "Mendix" instead of "we" in the regular documentation. Use "we" only in the Studio Pro release notes, which are written from the perspective of PMs or developers.
+> Create a microflow. (Instead of "Let's create a microflow.")
+>
+> Add validation rules. (Instead of "We can add validation rules.")
+
+When you need to emphasize that Mendix is the speaker, use phrasing like "Mendix recommends".
+
+> Mendix recommends using the latest LTS version for production environments.
+
+Release notes are an exception: they are written from Mendix's perspective and use "we" consistently.
+
+> We fixed a bug where the debugger would crash when inspecting large objects.
 
 ## Procedures and Examples
 

content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/product-naming-guide.md

@@ -86,9 +86,9 @@ It is fine to use "Control Center."
 
 ### Mendix Marketplace
 
-Capitalize in all instances, even when just writing "Marketplace."
+Capitalize in all instances, even when just writing "Marketplace." Use "Mendix Marketplace" on first mention in a document, then "Marketplace" for subsequent mentions. When there's risk of confusion with another marketplace (such as Siemens Marketplace), use "Mendix Marketplace" throughout.
 
-It is fine to use "the Mendix Marketplace" or "the Marketplace."
+This is a product name, so don't add a definite article.
 
 ### Mendix Platform
 

content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/terminology.md

@@ -43,17 +43,15 @@ Use "AM" and "PM" for times, via the MSG.
 
 Use to refer to "< >".
 
-## app/application
+## app
 
-Use "app" or "application" when referring to apps in general. Do not capitalize (meaning, do not write "Mendix App").
+Use "app" instead of "application" in most cases, as [recommended by Microsoft](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/app-application). Do not capitalize (meaning, do not write "Mendix App").
 
-The full word "application" has a more well-rounded meaning to it (i.e., web and mobile apps), whereas "app" may connote just mobile app to the reader. Accordingly, it can be better to use "application" at the beginning of documents and then switch to "app" later on. We want to make it clear that Mendix is not just for building mobile apps, but all kinds of applications.
-
-In the context of development and project management, sometimes using "project" can significantly enhance the clarity of the concept, as demonstrated in [Centralized Project Roles](/control-center/roles-and-permissions/#centralized-project-roles). In such cases, we can use "project" instead of "app" or "application". Note that such usage of "project" should be agreed upon between the Project Manager and the Technical Writer. For further guidelines, see [project](#project).
+In development and project management contexts, use "project" instead of "app" when it makes the concept clearer, such as in [Centralized Project Roles](/control-center/roles-and-permissions/#centralized-project-roles). For more guidance, see [project](#project).
 
 ## app owner
 
-This is not a formalized/Mendix term, 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 and interpret what an app owner is for their app.
+This is not a formal Mendix term, so do not assume users know what it means. Define it in general terms and make clear through context that each team must define and interpret "app owner" for their own app. For an example, see the *Copyright* section in the [Insights Hub module documentation](/partners/siemens/mindsphere-module-details/#configuring-the-os-bar).
 
 ## article, document, page