3

I usually highlight anything that should stick out from regular statements like a program name, a command, a string or a value by enclosing it between backticks, while I usually highlight something like an option (e.g. a drop-down menu entry) or a button label by enclosing it into double-quotes. Are those deemed like correct ways to do this? Are there better ways? Or better, is there an explicit and comprehensive guideline / convention which covers all those cases?

I'm asking this because I've seen my posts' formatting being edited many times, but I've never noticed a common pattern across the various edits, so it seems like everyone tends to use its very own, plus now that I'm reviewing suggested edits I'd like to estabilish an unique way for myself to review the formatting, possibly based on which way it's deemed to be the best for readibility since, again, everyone seems to use its very own.

1 Answer 1

4

There's no one right way to do it. Formatting that is clearly useful and that is applied consistenly within a post is generally good, and does not need to be changed by editing. Formatting that serves no purpose or that is applied inconsistently should be avoided, and fixed by editing when found.

In general when editing, I recommend trying to keep with the style the author has used, unless:

  • the current style is causing problems, or
  • there is no clearly identifiable style, whether because formatting is inconsistently applied or for some other reason, or
  • you are mostly rewriting or considerably expanding the post, and a different style seems better in light of these changes.

Since there is less of a "one right way" for formatting than for something like spelling or punctuation, formatting that is readable and consistent should usually be kept. (In contrast, if someone has spelled Ubuntu as "unbuntu" all nineteen times it appears in their post, this should still be fixed.)

Code Formatting

Depending on what you mean by "program name," it might not be a good idea to format that specially as code--or at all. When text refers to a command or executable, like sudo, software-center, and /bin/ping, it's often helpful to give it code formatting. But names of software, like "Ubuntu 14.04 LTS," "Software Center," and "Firefox," do not in general benefit from any special formatting.

  • I've enclosed them in quotes here, but only because in this case I am talking about the names themselves rather than the things named by them.
  • A good general rule is that only text that is codelike in some significant way or which requires code formatting to be efficiently readable should have code formatting.
  • Occasionally someone italicizes or bolds all the proper names and brand names in a post naming programs, hardware components, etc. This is not useful. Names that are incorrectly in lower case should be capitalized, but besides that there is no special way these names should be presented.
    Some projects/products and even a few people deliberately don't capitalize the first letter of their names even at the beginning of a sentence (e.g., mtPaint, iTunes, vSphere, qBittorrent, id Software, x86, µ-velOSity, nesC, o:XML, brian d foy, bell hooks). These don't need to be capitalized and, unless a capitalized alternate form is already widely accepted, shouldn't be.
  • This is not to say that such terms must never have special formatting, just that their function of naming software (or hardware, a person, etc.) is no reason to format them specially.

I think these examples are reasonably formatted:

I do not recommend automating LibreOffice Calc in COBOL, but if you do choose to attempt this, you need not run cobc with sudo.

In particular, a space after ~ or the first / will delete everything in your home folder, including all your AbiWord documents. I suggest cd ~/.config && rm -r abiword as a safer way to delete your AbiWord profile.

Labels in Graphical Interfaces

There are even fewer universally applicable guidelines when it comes to the formatting of text that labels command buttons, checkboxes, tabs, menu items, and other UI elements. I've seen--and, in various different posts, used--double quotes, italics, and bold.

Consistency within a post is still important, but this doesn't always mean using only one kind of formatting. For example, an author might choose to italicize the names of tabs and command buttons while enclosing checkbox labels in quotes. A paragraph like this in an answer is probably fine:

In the Software & Updates utility, click the Updates tab. Under "Install updates from," make sure "Important security updates (vivid-security)" is checked. Click Close.

But that is certainly not the only acceptable way to format it.

It's usually bad to use different formatting for the labels of multiple UI elements of the same type, such as two command buttons. Avoid this:

If you make a mistake, click "Revert." Otherwise, click Close.

Further Reading

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .