Is using `code` styling for non-code samples okay?

Question

The code is for code samples, of course. Its actual description is "a piece of program instructions." If package-names or date-and-time (technical details) are program instructions, then so are keyboard keys, graphic input, changes in settings, etc., because a computer can read them too.

In fact, nothing is computer un-readable as long as we're talking about things in the computer itself. Even a corrupt file can be read to give the error "Cannot open the file."

Here, a program instruction necessarily means only the instruction used to develop a program (and thus the name code).

However, instead of codes, this styling is also used for technical things like directories (usr/share/backgrounds), URLs (http://example.com), file names (and open the file database.odt), date (Access the files you created on 20/08/2014), Ubuntu commands (and press Super Key+2 to open it), etc.

It defeats the purpose of code styling. If it would've been called "technical markup" rather than code sample, it was okay, but it's not.

• We can define what comes in a code on the basis of Stack Overflow. There, it's used only for coding and programming samples to separate main content from code, not to showcase technical items.

• Many Stack Exchange websites that are not technical don't use code, even for date-and-time, URLs, path names, etc. This further proves the claim.

Answer 1

I think terdon's answer addresses the original question perfectly, but I'd like to address the added material.

What is code?

You object to formatting filenames like /home/ek/Desktop as code. How about ~/Desktop or ~ek/Desktop? Those are not technically filenames--they're patterns that get expanded by a shell to become filenames.

Another such pattern is:

/usr/src/linux-headers-$(uname -r)/Module.symvers

Is that also not code?

Even in a filename with no shell expansion, such as /usr/bin, there are often characters (like /, and some instances of .) with special technical meanings. Is writing a filename computer programming? No. Like writing HTML markup (which is universally recognized as code), writing a filename is not programming.

Are all filenames, taken individually, meaningfully code? Probably not. What I am saying is that what is and isn't code is fuzzy, and to pretend otherwise would be a mistake, both technically and from a site policy perspective.

The word for something isn't an authority, on AU or anywhere, on how it is to be used.

It defeats the purpose of code styling. If it would've been called "technical markup" rather than code sample, it was okay, but it's not.

Inferring directly, from what something is called, about how people ought to behave in relation to that thing, is a fallacy of reasoning.

Related: The Voice of Authority: Morality and Dictionaries by Kory Stamper

While I disagree with the idea that most of the sorts of things you're objecting to applying code formatting to are actually not code... even if they were not, there would be no weight to this argument.

Code formatting on things like file and package names does not cheapen it elsewhere.

As for "defeat[ing] the purpose": that would mean formatting filenames (for example) as code actually negates the utility of code formatting for whatever is to be considered "actual code." But it doesn't.

Using code formatting for emphasis is bad, mainly because it is jarring and distracting for ordinary prose text to be formatted in such a profoundly different way from the surrounding text in the same sentence or paragraph. When code formatting is used for emphasis, I think the only way to efficiently and pleasantly read a post is to try to ignore the formatting altogether. So that does also have the bad effect of "defeat[ing] the purpose" of code formatting.

But when code formatting is used for code-like text, not structured like natural language, and meaningful to a computer system, this does not apply.

Reading prose and coming upon something that's not intended as an actual word (like "/etc/apt/sources.list") constitutes a kind of interruption. We can let people do the work of identifying these elements, or we can do it for them with code formatting, thus making reading even easier.

Furthermore, it's often helpful for such text to be rendered in a monospace font, which is achieved by code formatting.

Ubuntu is not Stack Overflow.

We can define what comes in a code on the basis of Stack Overflow.

No, we cannot. Ubuntu is not Stack Overflow.

Each community has expectations about how posts will be written. Those expectations factor into how users read posts; not following them will sometimes make posts less readable.

The kinds of posts we get on Ask Ubuntu are different from the kinds they get on Stack Overflow. The community expectations that have evolved from those differences are themselves different. The advantages and disadvantages that arise when choosing one style over another are different here than there--they depend on practical factors that arise when writing about Ubuntu (versus writing about programming). Ubuntu and programming are overlapping topics but they're quite different and they do not mostly overlap.

We have way less use for text unanimously characterizable as "code" on Ask Ubuntu than on Stack Overflow, which is a question-answer site specifically about computer programming. So even if the use of code formatting for other purposes were damaging to a narrow class of things that are definitely code, the balance of harm and benefit associated with that would be different here than on Stack Overflow.

Furthermore, I think your statement of how code tags are used on Stack Overflow is a bit oversimplified. For example, suppose I write on Stack Overflow, "Every time I call foobar(), my program segfaults."

Is foobar() code? In the strict technical sense, no--not as it appears there. I am naming a function, not calling it--not presenting a fragment of code in the way it might be used. (Such notation is somewhat common in programming and typically does not imply that the function can even be called with no arguments.)

Would some people on Stack Overflow object to code formatting even in that situation? Probably. Does that reflect the views of all or virtually all active SO users? I doubt that highly.

Many Stack Exchange websites that are not technical don't use code, even for date-and-time, URLs, path names, etc.

We are not those websites. Also, there are other Stack Exchange websites where code formatting is used much as it is here, such as Unix.SE.

With that said, most URLs that don't appear in a code block with other text and which are linkified should not be formatted as code. I'm not familiar with any instances of people using code formatting for date and time, but if the only code-like thing about it is that it uses a date or time notation (e.g., "12:27 UTC"), it should not be formatted as code unless something about the context indicates otherwise.

Insisting people only ever use code formatting for "coding and programming samples" would be very harmful to the day-to-day operation of Ask Ubuntu.

Consider the following "code" blocks.

Error messages from apt-get:

Ign ftp://ubuntu.mirrors.tds.net trusty-proposed/universe Translation-en_US
Get:332 ftp://ubuntu.mirrors.tds.net trusty-proposed/universe Translation-en
Ign ftp://ubuntu.mirrors.tds.net trusty-proposed/universe Translation-en
W: Failed to fetch ftp://ubuntu.mirrors.tds.net/pub/ubuntu/dists/trusty/restricted/source/Sources  Unable to fetch file, server said 'Failed to open file.  '

W: Failed to fetch ftp://ubuntu.mirrors.tds.net/pub/ubuntu/dists/trusty/main/source/Sources  Unable to fetch file, server said 'Failed to open file.  '

W: Failed to fetch ftp://ubuntu.mirrors.tds.net/pub/ubuntu/dists/trusty/multiverse/source/Sources  Unable to fetch file, server said 'Failed to open file.  '

The output of a command, displayed in columns:

ek@Kip:/usr/local/gcc3/src$ ls
gcc-3.4.6      gcc-core-3.4.6.tar.bz2  gcc-testsuite-3.4.6.tar.bz2
gcc-3.4.6.old  gcc-g77-3.4.6.tar.bz2

The output of a command that is code-like, but not code in the strictest sense:

ek@Kip:/usr/local/gcc3/src$ mount | grep /sys
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
none on /sys/fs/cgroup type tmpfs (rw)
none on /sys/fs/fuse/connections type fusectl (rw)
none on /sys/kernel/debug type debugfs (rw)
none on /sys/kernel/security type securityfs (rw)
none on /sys/fs/pstore type pstore (rw)
binfmt_misc on /proc/sys/fs/binfmt_misc type binfmt_misc (rw,noexec,nosuid,nodev)
systemd on /sys/fs/cgroup/systemd type cgroup (rw,noexec,nosuid,nodev,none,name=systemd)

Entries from a configuration file (truncated):

# deb cdrom:[Ubuntu 11.10 _Oneiric Ocelot_ - Release i386 (20111012)]/ oneiric main restricted

# See http://help.ubuntu.com/community/UpgradeNotes for how to upgrade to
# newer versions of the distribution.
deb ftp://ubuntu.mirrors.tds.net/pub/ubuntu/ trusty main restricted
deb-src ftp://ubuntu.mirrors.tds.net/pub/ubuntu/ trusty restricted main multiverse universe #Added by software-properties

## Major bug fix updates produced after the final release of the
## distribution.
deb ftp://ubuntu.mirrors.tds.net/pub/ubuntu/ trusty-updates main restricted
deb-src ftp://ubuntu.mirrors.tds.net/pub/ubuntu/ trusty-updates restricted main multiverse universe #Added by software-properties

None of those are code in the very strictest sense. The last one is pretty close. The first two, especially, seem like the sort of thing you're saying should not be formatted as code.

If you think any of the four of these can be reasonably presented without code formatting, try it. The monospaced, even code-like nature of text displayed on the terminal indicates that blocks of text from the terminal should almost always be formatted as code.

That, right there, is a huge violation of the idea that only "a piece of program instructions" should be formatted as code. But we need to use code formatting, to make such text readable.

The needs of our site are determined by the mission and users of our site and the content we create on it, not by the rules set by and for some other site, and ultimately not even by abstract principles.

Answer 2

As a general rule, code should be used exclusively for things that a computer would understand. This includes code, commands, paths, package names etc. URLs don't need it but it's OK to use them to avoid making the URL into a link.

What you should never do is use code for emphasis, to highlight an important part of your post. That is just ugly and makes your post much harder to read.

At the end of the day, you need to ask yourself whether adding the code block makes your post easier to read. If the answer is yes, then great. If it is no, then remove the code blocks even if they are being used correctly. Not all command names need to be in code blocks for example, sometimes having them improves readability so they're fine and useful, sometimes it doesn't so avoid them.

Answer 3

Why not?

In fact, sometimes it is used for package names.
Sometimes its even used for something completely unrelated to code e.g. when you want to show a url without making it a link http://www.example.com. I'm pretty sure it's been used lots of other ways as well.

If that didn't convince you, you have used it yourself for a non-code sample. You used it to show an example.

Answer 4

There are two more places where I would use code formatting:

1. Output from a computer program. In this answer, for example, I would have recommended using code formatting for the output of dpkg-query -l.
2. Text where non-monospace fonts might cause confusion (0/O/o, l/1/I). Typically this happens only in the situations already covered by terdon, but if I did have a word or line with this problem, I'd use code formatting.

Answer 5

Yes. The `code` styling is rendered using <code> tag, and according to HTML 5 specification:

The code element represents a fragment of computer code. This could be an XML element name, a file name, a computer program, or any other string that a computer would recognize.

The <code> tag does not necessarily have to be program code, it can be any computer code. File names, package names, and URLs are clearly computer code.

Keyboard keys can be argued to be computer code, however the <kbd> tag is more suitable for that, and therefore should be preferred for keyboard keys.

A path to find a settings can (e.g. System Settings > Keyboard > Repeat Keys) is analogous to a file path.

Date-time though, unless it's in a format that is computer-friendly, is most likely not an appropriate use of `code` markup.