Add guidance about referring to UI elements versus referring to other publication titles

[julian-cable]

I think that a distinction should be made between referring to UI elements and referring to publication titles.

For referring to UI elements, IBM says:
"When you write about an item that is displayed in a graphical user interface, match the capitalization and spelling of the
item in your writing. For example, if a label is displayed with initial uppercase letters or all uppercase letters, write the
label the same way in the documentation. However, if the text in the interface contains a spelling mistake, use the
correct spelling in the documentation, and have the mistake corrected."

For referring to titles, IBM says:
"Use headline-style capitalization for these items:
Titles of books
Titles of CDs
Titles of stand-alone information units, such as quick start guides or discrete sets of product documentation
Titles of events, such as training courses or programs
Titles of videos"

For referring to titles, CMOS says:
"Titles mentioned or cited in text or notes are usually capitalized headline-style."

From these sources, I would suggest:

• For referring to UI elements, we should indeed match the style used in the interface, except for any spelling errors.
• For referring to publication titles, I think we should adopt our usual standard (title case) rather than emulating the style of the title at its source.

[bonnevil]

"However, if the text in the interface contains a spelling mistake, use the correct spelling in the documentation, and have the mistake corrected." -- makes sense for documentation being done in close conjunction with development of the software. I'd argue that for training we should use the existing (incorrect) spelling from the interface, but have the mistake corrected and fix the error when engineering publishes the fix and we get the fix in the version of the software used by the course.

[julian-cable]

@bonnevil I think rather that we should apply correct spelling in the training even if the software cannot get fixed immediately. I don't think that we should ever deliberately introduce incorrect spelling.

[bonnevil]

@julian-cable Speaking as a devil's advocate: I get the reason, and even sympathize to some extent. But we're going to have outliers like the legendarily bad HTTP Referer field; "referrer" was misspelled in the 1995 standard and it's expected to never get fixed in practice. If the interface element has a certain spelling, and the book has a different spelling, does that necessarily make sense when the student is looking for the interface item?

[bonnevil]

Note in the preceding case, I'd only use the bad spelling if referring to the item by name; we'd still be talking about getting information about the "referrer" with the correct spelling.

[julian-cable]

@bonnevil An interesting question indeed. Do you think that in some cases you would be inclined to use corrected spelling, but in other cases (such as in your example, perhaps on an exception basis) to keep the incorrect spelling to avoid student confusion? Also, in such a case, might you be more inclined to write about the item rather than naming it specifically, to work around the problem? Just curious.

[bonnevil]

@julian-cable It's possible. In general, yeah, if something is broken (like the misspelling) and there's a way to write around it that would avoid triggering the issue without seeming stilted/artificial, then I might do that. And I can imagine situations where using the corrected spelling would make more sense (possibly even with a note that the spelling was incorrect in some specific version of the interface/software). I think this is one of those situations where the context might really matter.