Fixing <code> when it's part of a word

[sheppy (Eric Shepherd)]

Sometimes we use <code> when it’s part of a word, such as <code>Window</code>s to get “Windows”. This is not uncommon, and is an important case, since Windows is not actually an interface name.

The problem is that in the revised design with the background color on the <code> element, the padding added to the sides results in a large gap between the “<code>Window</code>” and the “s”, so it looks to the eye like "<code>Window</code> s".

This is bug https://bugzilla.mozilla.org/show_bug.cgi?id=1399529. There’s a screenshot that shows this problem here: https://bugzilla.mozilla.org/attachment.cgi?id=8909412.

You can see an example page that demonstrates several cases in which this problem arises here: https://developer.mozilla.org/en-US/docs/User:Sheppy/Bug1399529

[sphinx_knight]

For what it’s worth, when localizing, I tend to avoid this kind of <CodeWord><suffix> (e.g.Windows) structure since it doesn’t really mean anything in my locale.
Either the sentence is about the “functional” object (e.g. “the window’s background will turn red”) or it is about the technical API (“the Window API contains the method x(), etc.”, “the Window objects contained in the array”).

I know this takes place for me because English is both used for common nouns and “code” stuff since it’s the lingua franca but I like to maitain this separation of concern so that reader don’t get confused and identify the different concepts.

That being written, I agree that “typographically”, spaces before punctuation could be reduced a bit more (which is totally a subjective opinion).

[Stephanie_Hobson]

There isn’t a way to change this only in cases where a letter follows the <code> element with no whitespace between. Any improvements will apply to all instances.

Here are some possible options for improvement:

No padding

Reduced padding:

Use box shadow instead of padding:

For comparison here is the example without any changes:

---

The box shadow option sucks the punctuation into the background which could be confused as meaning it’s part of the code.

We got complaints about the legibility of the headings when they had no padding on them.

I think I prefer the reduced padding option but I’d like to know what everyone thinks.

Stephanie.

[chrisdavidmills]

I think I prefer the reduced padding option but I’d like to know what everyone thinks.

I agree — I think reduced padding looks to be the best of the bunch.

[Shi]

I think, too, that the reduced padding is good.

[sheppy (Eric Shepherd)]

I actually like the box shadow one the best by far given the examples above. They look so much better and more readable; enough padding to stand out but they don’t lose the added characters into the void.

You mentioned that the box-shadow case doesn’t work well with punctuation but there isn’t an example of that here, so it’s hard to be sure what to think of it.

Reduced padding is an improvement but is still a little gappy. But at least it no longer looks like a wide space.

Eric Shepherd
Senior Technical Writer
MDN Web Docs: https://developer.mozilla.org/
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy

[wbamberg]

Just as a matter of style, I agree with Sphinx that we should discourage things like “Windows”, and prefer to use things like "Window objects".

[chrisdavidmills]

Oh, totally — we should avoid them where possible.

[atopal (Kadir Topal)]

Hmm, this all still feels like it would disrupt the reading experience. Maybe part of the problem is that the “s” has an x-height that’s 10% larger than the text before it and uses a different font. I agree that going without the suffix is probably the cleanest way to avoid this issue, but I can also see how that might lead to sentences that are unnecessarily complex.

Here’s an example with font-size for “code” increased to 110% and no padding on the right:

[sphinx_knight]

Agreed to the reduced padding option.

[sheppy (Eric Shepherd)]

ust as a matter of style, I agree with Sphinx that we should discourage things like “Windows”, and prefer to use things like “Window objects”.

I disagree. I think that often leads to overly convoluted text. Yeah, sometimes we should make that call, and I do, depending on the surrounding text, but doing it all the time just introduces unnecessary wordiness and formality into the text.

Eric Shepherd
Senior Technical Writer
MDN Web Docs: https://developer.mozilla.org/
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy