Docs/specs/syntax

These are Zabbix rules regarding element naming, grammar usage etc. Primarily for frontend.

Contents 1 Syntax 2 Formatting 3 Referencing 4 Grammar & style 5 Naming 5.1 General 5.2 Operations 5.3 Entities 5.4 External names 6 Language rules 6.1 Latvian

Syntax

1. Random words should never be capitalised in the middle of a sentence or label. "Incorrect characters used for host", "Create host" etc should be used.
   1. Exception : Failure Audit, Success Audit - Windows Eventlog levels which are capitalised like that in original
2. Names like "host name", "host group", "proxy name", "node name", "template name", "media type" should always be written separately
3. For referencing bytes with a multiplier prefix, KB, MB etc syntax should be used.

Formatting

1. Entities (hosts, items, item keys...) should be referenced by enclosing them in double quotes, without additional characters - "like this". (Square brackets are already used for item parameters, asterisks are not commonly used and look confusing)
2. Main status messages like "Host added" (displayed on green/red background at the top of the page) should never end with a dot. Detail (expandable) messages should always end with a dot.
3. Detail messages follow the syntax of :

   Action: Object "Object name" on "Host name".

   1. Host part is only printed if relevant for the object (for example, it won't be printed for actions and network discovery rules).
   2. Example : "Created: Item "Free memory" on "Database server".

Referencing

1. All entities (items, triggers, custom graphs, applications etc) are always referenced by host and entity name.
2. In user visible messages, comments, documentation etc trigger functions should have empty set of parentheses added after function name, for example, last().
3. If a user is expected to provide the reference (for example, item key in trigger expressions, calculated item formulas, macros used in network map labels etc) and gets it wrong, error message uses the provided item key to let the user know which reference failed. Example message:

   Item with key "key" on host "host" not found.

Grammar & style

1. "Can't" vs "Cannot" - only the expanded form "Cannot" should be used
2. The user should not be addressed, e.g., "No targets specified" should be used instead of "You did not specify targets"
3. "checksum" not "check sum"
4. "No n defined" (as in "No graphs defined") - always plural (not "No graph defined")
5. "Incorrect parameter" - always "Incorrect parameter[s] for..." (not "Incorrect parameter[s] [is|are] [used] for...")
6. Use "Acknowledgments" as the name in plural for the function of acknowledging
7. Keep in mind that some words in English may have irregular formation of plural ("medium" sing. -> "media" pl.). In case of doubt, double check
8. Macros are "expanded" (not "resolved") - Google search returns ~ 58 million for the first and ~ 18 million for the second.
9. Trigger relationship is always described using words "dependency" and "dependencies" (not "dependence" and "dependences")
10. "Minimum" and "maximum" instead of "minimal" and "maximal", e.g. "The minimum value" (note the use of the definite article). "Minimal" would represent a small amount, while "minimum" would represent the smallest possible (and similar for "maximum").

Naming

General

1. GUI -> Frontend (easier to translate)
2. An ID should be referenced by a lowercase object type and a space-separated uppercase string "ID" - for example, "host ID" or "template IDs"

Operations

1. If an entity is created/deleted, verbs "create" and "delete" should be used
2. If an entity group membership is modified, verbs "add/remove" (as in "Added to group") should be used
3. For template operations verbs "link/unlink" should to be used. For example, if templated entities are removed, this action should be called "Unlink and clear" or if it is a separate option - "Clear when unlinking".
4. what about applications ? what verbs should be used to note item - application changes ? "item linked to application" or a different one ?
5. Entities are always enabled and disabled (not activated/deactivated).
   1. For action to be performed: Enable/Disable
   2. For state: Enabled/Disabled

Entities

1. Maps - links instead of connectors
2. Interval vs Delay
   1. Interval should be used for:
      1. Items in the frontend and XML
      2. Network discovery (currently "Delay")
      3. Action escalations (currently "period", should be "step interval")
      4. Web monitoring (currently "Update interval"
   2. Delay should be used for:
      1. Slideshows
3. Entity name is always called "Name" (not "Description") - items had "description" up to 2.0
4. external scripts (config file) or external checks (frontend) ?
5. "Network discovery" is always referred to as that (not auto-discovery etc)
6. "Active agent auto-registration" or "Auto-registration"
7. "Low level discovery"
8. remote actions -> remote commands
9. system maps -> network maps (just maps somehow ? how about consistency ?)
10. frontend scripts ? scripts ? global scripts ?
11. user alias -> user name
12. "Metric" should not be used. Either "item" or "value", depending on what it describes
13. "Inventory", not "profile" (as in "Host inventory") ZBXNEXT-863
14. nodes - master/slave, parent/child ? zabbix uses all versions randomly
15. messages being sent out database has "alerts", frontend mostly uses "actions" (Administration -> General -> Housekeeper has Do not keep actions older than (in days), Administration -> Audit has Actions in the dropdown and page header - and there's also Administration -> Notifications... and these also do include remote commands
16. It should always be clarified what type of an entity something is
    1. Not just "group", but "user group", "host group" etc
    2. "Required field "expression" is missing in icon mapping.", not "Required field "expression" is missing in mapping."
    3. Type may be skipped if the message already implies it, for example, "Icon map "%s" cannot have mapping with empty expression."
17. Both item keys and trigger functions have "parameters" (not "arguments")
18. rights or permissions ? permissions seems to be a bit more specific & better
19. Trigger severity (not priority)

External names

• Instead of just "DB2" use "IBM DB2" because there is also Berkeley DB2 database

Language rules

Latvian

• Jautājumi vienmēr sākas ar "Vai..." - "Vai dzēst..."
• "Nav iespējams" paziņojumi ir šādā formātā: "Karti 's' nav iespeejams izdzeest"
• izveeleetos/ieziimeetos ?

also see ZBX-3629