Update language on Naming conventions (#133)

* Update Naming Style

Add rules for title-case conventions.

* Update naming.md

Refining language

* Update designguide/naming.md

including command names, in context of FreeCAD they are considered proper nouns and should be capitalized when referenced as such in text.

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* Update naming.md

removing duplicative langauge

* Update naming.md

* Update naming.md

update about source-code references in the UI

* Update naming.md

Updating grammar and improving language

* Update designguide/naming.md

spelling

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update naming.md

correct for standard quotation marks

* Update designguide/naming.md

Co-authored-by: Max Wilfinger <[email protected]>

---------

Co-authored-by: Max Wilfinger <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

designguide/naming.md

@@ -1,42 +1,61 @@
 ## Naming Convention and Writing Style
 
-Due to the technical nature associated with CAD and advanced programming, it is easy to fall into the trap of using terminology that is either overly descriptive or seems obvious as a developer but is obscure to the layman. Additionally, with so many functions at a user's disposal within FreeCAD, screen space comes at a high premium, and text strings can quickly change a UI/UX from being concise and efficient to awkwark and unpleasant. The following guidelines should be considered when naming/labeling functions, features and other various addons.
+Because FreeCAD involves both CAD and programming, it's easy to use overly technical or redundant language. Names that seem obvious to developers may confuse general users. Additionally, with limited UI space, concise and clear naming is critical for usability. Follow the guidelines below when naming or labeling functions, features, and add-ons.
 
-*NOTE: This area is highly subjective as FreeCAD is translated into many languages, however English is considered the standard by which naming will be assessed. It will be up to various translators to best adhere to these guidelines as best as possible.*
+> **Note:** While translations exist, English is the reference standard. Translators should follow these guidelines as closely as possible for the target language.
 
-Efforts should be made to conserve space within the UI in order to prevent elements from needing to be resized from workbench-to-workbench or dialog-to-dialog. Word choices should be reviewed before merging a pull-request with text elements in the GUI.
+Avoid verbose or inconsistent language in the UI, as it may cause layout issues across workbenches and dialogs. Always review naming before merging UI-related pull requests.
 
 ### Language
 
-- Use the shortest descriptive words possible for a function. Single words are preferred, however this will not always be possible. For example use `Additive cube` instead of "Add additive Cube" or "Create new additive cube" for naming the command. Tooltips can be more descriptive, but concepts and functionality should be explained in the documentation.
-- Do not use verbs in the command name itself where not needed and try to avoid "Create", "Add", "Insert" in the command name. Example: `New File` is sufficient, the command should not say "Create new file". It can be relevant if the action is not obvious, e.g. `Insert image` (just "Image" would not be enough). Instead of verbs use nouns in the command name, where the most important word should be in the beginning: `Horizontal constraint` instead of "Constrain horizontal" (otherwise all similar commands start with constraint).
-- Use third-person present tense in tooltips or hints. `Creates`, `adds`, `sends`, `opens`, etc. and write tooltips and hints as complete sentences, starting with the verb where possible.
-- Describe the action or result in tooltips: say what the command does and what is needed (e.g. active body or selection), do not only repeat its name. Be specific if possible: instead of "Add sketch" write `Adds a new sketch to the active body`.
-- If a text is valid for one or multiple actions use always plural, e.g. `Creates holes based on the selected profiles` not "Creates hole(s) based on the selected profile(s)".
-- Do not add additional information which is obvious or list multiple steps like "Select one or more line(s) click this button, add dimension". Better: `Inserts a dimension for the selected lines`.
-- Avoid redundant descriptions of states in tooltips and notes. Example: instead of "If checked by the user, the view is updated automatically", "If active,..." or "This option controls..." use `Updates view atomatically`.
-- Avoid addressing the user directly or in third person. Do not write "Click this button" in the tooltip or "Select something then do this". Instead describe in a short sentence what the command does with which inputs without asking the user directly.
-- Broadly accepted and understood acronyms can be used in place of full words (e.g. `CAD` or `ISO`), however, these should be scrutinized closely by the design and development teams to avoid obscure references.
-- Write numbers in arabic numerals (`0, 1, 2,...`) not spelled out ("one, two,...")
-- For concepts already used within FreeCAD, use the same wording so those concepts remain consistent wherever possible.
-- Avoid using common programming terms, preference should be given towards more plain language words.
-- For all user-facing strings add comments to help adding context for translators `//: Sketcher: Command name for new line`. More info in the [Qt docs](https://doc.qt.io/qt-6/i18n-source-translation.html#add-comments-for-translators).
-
+- Use short, descriptive terms. Prefer single nouns when possible: `Additive Cube`, not "Create new Additive Cube".
+- Favor unique noun-first naming: `Horizontal Constraint`, not "Constrain Horizontal".
+- Avoid unnecessary verbs in command names (`New File`, not "Create new file"). Use verbs only if clarity requires them (e.g. `Insert Image`).
+- For items with optional plurality use plural language: e.g. `Creates holes based on the selected profiles` not "Creates hole(s) based on the selected profile(s)".
+- Do not add additional information which is obvious or list multiple steps like "Select one or more line(s) click this button, add dimension". Better: `Insert dimension for the selected lines`.
+- Acronyms like `CAD` or `ISO` are allowed but should be reviewed for clarity.
+- Use standard numerals (`0, 1, 2,…`) not spelled out ("one, two,…")
+- Keep terminology consistent with existing FreeCAD concepts.
+- Avoid programmer jargon in favor of simpler terminology.
+- For user-facing strings add comments as needed to help provide context for translators `//: Sketcher: Command name for new line`. [More info]([Writing Source Code for Translation | Qt 6.9](https://doc.qt.io/qt-6/i18n-source-translation.html#add-comments-for-translators)).
+- Use **third-person present tense** in tooltips: `Creates`, `Adds`, `Inserts`. Write complete sentences where appropriate.
+- Tooltips should describe the action and required context. E.g., `Adds a new sketch to the active body`, not just "Add sketch".
+- Avoid step-by-step instructions in tooltips. Focus on outcome: `Inserts a dimension for the selected lines`, not "Select one or more lines…".
+- Avoid stating the obvious: "If checked by the user, the view is updated automatically", use `Updates view automatically`.
+- Don't address the user directly: say what the command does, not "Click this button…".
+- Avoid direct source-code references in the UI, instead of "This feature only works with PartDesign bodies" use `This feature only works with Part Design bodies`
 
 ### UI Text Style
 
-Use **sentence case** for all user-facing UI text, including buttons, menu items, tooltips, labels, and settings. Sentence case means only the first word and proper nouns are capitalized, and complete sentences end with a period. This makes the user interface visually less distracting and easier to read. For the same reason, avoid contractions like for example "don't" or "can't" - write `do not` and `cannot` instead.
+Use **Title Case** only for command names, buttons, menu items, and group titles. All other text should use normal **sentence case**.
+
+**Do not use periods** on short UI elements like buttons or labels. Use them only in full-sentence tooltips or descriptive text.
+
+**Use ellipsis (…)** at the end of menu items or commands that require user input. Do not use three periods "..."  instead of the ellipsis character `…` for consistency.
+
+Do not put a colon or space at the end of labels that are followed by required user input (e.g. QLabel for input box, button, dropdown, or checkbox) or headers. Instead of "X direction: " write `X direction`
+
+### How to Implement Title Case
+
+In title case, capitalize the following words:
+
+- the first word of the title or heading, even if it is a minor word such as "The" or "A"
+- major words, including the second part of hyphenated major words (e.g., "Self-Report", not "Self-report")
+- words of four letters or more (e.g., "With", "Between", "From")
+- capitalize the last word in the label, regardless of the part of speech.
 
-**Do not use periods** at the end of **short** UI strings like menu items, button labels, and checkbox texts. Use a period on tooltips and longer text elements, if they contain a full sentence. Omit the period if the tooltip is a short phrase or label.
+Lowercase only minor words that are three letters or fewer:
 
-**Do not capitalize commands or object names** unless it is a technical term that is capitalized in general.
+- short conjunctions (e.g., and, as, but, for, if, nor, or, so, yet)
+- articles (a, an, the)
+- short prepositions (e.g., as, at, by, for, in, of, off, on, per, to, up, via)
 
-**Use ellipsis (...)** at the end of menu items when specific input from the user is required for the action.
+**Examples:**
 
-**Example:**
-- `Constrains new geometry automatically. It is recommended to leave it enabled for most workflows.` - Complete sentences end with a period.
-- `New file` - This is just a short label. A tooltip for that command button would be "Creates a new file".
-- `Save as...` - The function requires user input to function.
-- `Addon manager` - This is not a simple action, so no ellipsis.
+- Tooltip: `Constrains new geometry automatically. It is recommended to leave it enabled for most workflows.` - Complete sentences end with a period.
+- Hint: `Toggles the visibility of the active sketch` - No period at the end
+- Command: `New File` - This is just a short label. A tooltip for that command button would be "Creates a new file".
+- Command: `Save As…` - The function requires user input to function.
+- Command: `Addon Manager` - This is not a simple action, so no ellipsis.
 
 [Return to Design Guide Main Page](index.md)