0

I am writing a white paper about a software product. This software product uses some common names in a specific way. For example, there is an "Actions" palette that contains items called "actions". There is a "Slides" palette that contains items called "slides".

When first referencing these items I can do as I did above, put the word in quotes. However, when I later continue to reference these terms in a manner that may be confusing to the reader how should I format them to best remind the reader that these are the specific items discussed earlier? There are also cases where the same word is used not as a reference to these items, and so I want to disambiguate the usages.

For example:

All user interaction is handled through triggers known as “actions”.
[…paragraphs later…]
Conditional interactions are accomplished by placing actions only on specific slides for items in the interface.
[…pages later…]
SCXML supports actions on state entry/exit, actions on transitions, …

The bolded usage of "actions" above refers to the specific term. The two italicized usages of "actions" above are (somewhat confusingly) references to a different concept.

  • Should I capitalize the reference? e.g. "…accomplished by placing Actions only on specific…"
  • Should I quote the reference? e.g. "…accomplished by placing 'actions' only on specific…"
  • Should I italicize the reference? e.g. "…accomplished by placing actions only on specific…"
  • Should I bold the reference? e.g. "…accomplished by placing actions only on specific…"
  • Should I leave the reference alone? e.g. "…accomplished by placing actions only on specific…"
4
  • 2
    This question appears to be off-topic because it is about User Interfaces, not English as such. I think it should be migrated to User Experience Stack Exchange Apr 9, 2014 at 16:24
  • @FumbleFingers I am writing technical documentation (actually, a white paper) that describes and discusses a user interface. This is about the English conventions for such writing. It would be the same question if I were writing about a race of people who called a specific piece of sacred jewelry a "thing", and I had to describe "When they put their 'things' on in the morning…"
    – Phrogz
    Apr 9, 2014 at 16:36
  • 'First, define your terms.' Throughout this article, the term 'action' will be used solely with the sense ... Apr 9, 2014 at 18:25
  • @EdwinAshworth This is perhaps a good suggestion, though as I've shown above I have a need to sometimes use the same term to reference a different, more generic concept.
    – Phrogz
    Apr 9, 2014 at 19:16

1 Answer 1

2

I would avoid using bold as this is usually used for emphasis, not designation. Italics could work, but not if you have many types of "actions" to differentiate.

Repeated quotation marks can look like overkill, plus may affect readability (as people try to "say" the quote marks in their head).

I think you definitely need to make a distinction between your different senses of "actions" as well as avoid confusion with usual senses of the word, so not doing anything is not a good idea.

Capitalization is in my view a good compromise, especially for the palette, as this could justifiably function as the name of the palette. However, using capitals for both the palette and the items would lead to the same confusion your are trying to avoid.

My suggestion would be to use "tag words". For example:

"Actions palette" and "Slide palette" (with or without the capital letter) throughout and then whatever tags work for the other types of actions, eg, "actions folder", "actions command", or whatever they are.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.