Is there a benefit to adding the punctuation symbol in parentheses when referring to punctuation?

Question

In writing documentation when referring to punctuation such as a comma, is there a benefit in readability to include the symbol of that punctuation character in parentheses afterwards?

For example, is this sentence:

When you refer to a web address that is long, add a line break before a forward slash (/) if possible.

... more readable than this:

When you refer to a web address that is long, add a line break before a forward slash if possible.

Or is this only adding complexity?

If a user is unfamiliar with the name of punctuation, could they not search for it to understand what it is? On the other hand, adding the symbol is helpful with troublesome punctuation such as colons/semicolons, hyphens, em-dashes, etc.

Would it be more beneficial to only include troublesome punctuation? Or is consistency more practical?

And finally, from a UX point of view, would only the first occurrence of the punctuation symbol be used so as to limit repetition?

Answer 1

To be clear, concise, and avoid ambiguity in documentation provides assurance and consumers of the documentation. Certainly with technical documentation, the author should strive to avoid ambiguity.

I would go further and refer to a forward-slash (/) and other punctuation (e.g. full-stop (.), exclamation mark (!), etc.) containing the character between grave accents / backticks (`). Despite what the Wiki has to say on grave accents[1], you will find a resurgence in their use in modern communication and documentation systems, stemming from their inclusion in the markup language known as Markdown (e.g. on StackExchange, Slack, and many more), though intended to contain and display code it is also useful for highlighting characters or anything of significance that is being referred to [2].

"And finally, from a UX point of view, would only the first occurrence of the punctuation symbol be used so as to limit repetition?"

Typically fine to do, perhaps include a Glossary of Terms for easy reference. Do consider use-cases for the document: is there a high probability of quick lookups compared to full document reads? If so, it would help to provide disambiguation inline (i.e. include repetition).

note: to contain a backtick within backticks, use double backticks to contain and have a space before an after the contained backtick.

[1] https://en.wikipedia.org/wiki/Grave_accent

[2] https://www.ionos.com/digitalguide/websites/web-development/markdown/