[ZBX-21700] Inconsistent use of commas in documentation Created: 2022 Sep 27  Updated: 2024 Apr 10  Resolved: 2022 Nov 01

Status: Closed
Project: ZABBIX BUGS AND ISSUES
Component/s: Documentation (D)
Affects Version/s: 5.0.28, 6.0.9, 6.2.3, 6.4.0alpha1
Fix Version/s: 6.4 (plan)

Type: Documentation task Priority: Trivial
Reporter: Artjoms Rimdjonoks Assignee: Martins Valkovskis
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Team: Team D
Sprint: Sprint 93 (Oct 2022)
Story Points: 0.5

 Description   

In exactly the same places, sometimes commas are used and sometimes they are not used.
For example, on master
"Now" with comma:
documentation/en$ grep -rI "Now," --include="*.md" .

./manual/quickstart/notification.md:Now, with delivering notifications configured it would be fun to
./manual/introduction/whatsnew640.md:Now, when Zabbix proxy, if it uses SQLite3, on startup detects that the existing database file version is older than
./manual/introduction/whatsnew640.md:Now, *heartbeat sender* is removed from a proxy, and therefore, Zabbix proxy *zabbix [process,heartbeat sender]* item is
./manual/appendix/install/okta.md:7\. Now, navigate to *Assignments* tab and press the "Assign" button,
./manual/appendix/install/locales.md:Now, run:
./manual/web_interface/frontend_sections/dashboards.md:Now, when saving the dashboard, you will notice that a new host
./manual/config/items/plugins.md:Now, these names may be used as connStrings in keys instead of URIs:
./manual/config/visualization/maps/links.md:a green line. Now, with the trigger in the problem state, your link may
./manual/config/notifications/media/webhook.md:    Redmine, ServiceNow, Slack, Zammad, and Zendesk webhooks provided by

"Now" without comma:

grep -rI "Now " --include="*.md" .
./manual/config/items/itemtypes/ipmi.md:IPMI checks by IPMI pollers. Now a host is always polled by only one
./manual/config/items/itemtypes/snmp.md:Now save the item and go to *Monitoring* → *Latest data* for your SNMP
./manual/config/visualization/maps/map.md:with a name, dimensions, and certain preferences. Now you need to add
./manual/config/visualization/maps/map.md:Now that you have some elements in place, you may want to start
./manual/config/triggers/dependencies.md:Click *Update*. Now the trigger has an indication of its dependency in
./manual/config/notifications/unsupported_item.md:And that's it, you're done! Now you can look forward to receiving your

The same inconsistent use of commas is also detected for introductory words:

Note,
Note that,
Also,
For example,
Finally,

probably there are others.

Documentation team must establish the policy on the use of commas and fix the inconsistencies in documentation.



 Comments   
Comment by Martins Valkovskis [ 2022 Oct 05 ]
  • The rules of using commas are governed by English grammar (there are many credible sources e.g. Webster for American English, Oxford for British English)
  • There is no grammar rule mandating the use of commas around "now"
  • There is no grammar rule prohibiting the use of commas around "now", if the reason is legitimate (for example, a word or sentence part that requires commas ends before or starts after "now")

Based on the above, the claim of general inconsistency is not valid. So WON'T FIX.

Comment by Martins Valkovskis [ 2022 Oct 27 ]

Individual cases of comma use can always be reported, especially if:

  • the use of commas creates actual misunderstanding for users
  • it is clear that a known grammar rule is broken
Generated at Fri Apr 11 04:36:07 EEST 2025 using Jira 9.12.4#9120004-sha1:625303b708afdb767e17cb2838290c41888e9ff0.