Topic on Help talk:CirrusSearch

Hi all. I had a lot of trouble understanding the #Prefix and namespace section, so I did my best to make it more readable.

Specifically confusing was term vs. term:, so I tried to make that more consistent within that section. When I see code, the programmer part of my brain thinks "oh, I type this in." Italics is used in prose for emphasis, is not very visually distinctive, and therefore doesn't trigger the same "oh, I must do something!" response. So I hope it makes sense why I think term: is preferable here.

Secondly, the HTML ‎<kbd> tag is typically used to denote hotkeys, such as Control+c, but I had a look at the MDN docs and it seems that using it for strings of literal text input is OK, too. What would be the preference then, ‎<kbd> or ‎<code>?

Would it be helpful to do a pass over the whole article, or the whole batch of CirrusSearch user-facing documentation, in order to make the use of ''term'' / <code>term</code> / <kbd>term</kbd> more consistent? --Ernstkm (talk) 03:17, 12 November 2023 (UTC)

Thanks for improving the documentation!

I think clarity is the most important goal, but consistency almost always helps with clarity. A lot of what the italics and <code>/<kbd> markup is trying to get at is the use–mention distinction. The problem is that there's no consistency on how to format mentions, and different traditions vary, so we are collectively not always consistent.

Adding the monospaced <code> or <kbd> to the mix lets us make finer distinctions (linguistics does this kind of thing, too, sometimes using both italics and quotes for different mentions, and mixing single and double quotes: He said, "I told my cat that gato means 'cat' in Spanish.") Search discussions often use italics rather than quotes so we can mention quotes: You should search for "pet" dog cat. And like you, I tend to interpret monospaced text as things I could type; I guess it's a tech-flavored mention.

I guess I'm mostly agreeing that it's a mess, but I think that trying to make another finer distinction between <code> and <kbd> would only make it messier and harder for newcomers to understand or contribute. Since ⌘ Command+⇧ Shift+6 (on a Mac) generates <code> tags, that's probably the best thing to standardize on—unless clarity of formatting creates a reason to use <kbd>, too.

OK, I agree, and thanks for the lesson on "use-mention distinction." I guess I intuitively knew that was a thing, but didn't know its name.

I'll go ahead and replace the <kbd>s with <code>s. I thought the use of <kbd> was a little odd anyway, given that it's used on other sites like Stack Overflow and GitHub specifically to indicate keypresses, and gets styled like keycaps, in the same way that {{key press}} is used here.

…or not. There are 420 uses of <kbd> in the article. I could search-and-replace all of them, but I'm not sure that improves the article materially. Leaving as is for now.

> …or not. There are 420 uses of <kbd> in the article.

Fair enough!