7

EDIT:

Since a bunch of people are going tl;dr and wall-of-text, an example.

Basically, is there anything "wrong" about the way I changed the readability of my answer from its original edition, "version 1" to its current form?

General feedback and criticisms on the formatting, readability and use of Mr. Backtick (`) would be especially appreciated.

The original "tl;dr"/wall-of-text question:

Without being able to find anything resembling a standard on, or even discussion of, this topic (using the search, of course), when I've come across [recent] posts that are otherwise fine, except that they seem like they could benefit from some readability/formatting improvements, I've thus far been just doing what "looks" best and easiest to read to me.

Particularly with the usage of the backtick character (`), I'm rather curious as to how the community feels it "should" be used. Lately, I seem to have seen or noticed a lot of what I presume to be different opinions, and even variations on "accepted usage" across SE sites.

One from today sticks out where someone on the English stack exchange site edited an answer to remove two ` characters and left a comment along the lines of ~"that formatting markdown has a specific meaning, don't use it like that," without explanation on how it should be used, naturally.

Even in my edits and posts I've seen a lot of superseding edits where the use of ` was completely reversed or even rolled back on the basis of its use, so it seems like a good time to pose the question and maybe even achieve some clarity on the issue. For example, here. (Not to single out or complain about @MDMarra 's superseding edit in any way, because it is an edit that improved the post, but it illustrates a diametrically opposite opinion on the usage of the backtick formatting between myself and him.)

Basically, as I understand it/think, it's to be used for inline distinction of, um... "not actual words" (for lack of a better way to phrase that), like one would use the > markdown, only, inline, given it applies the same type of format as the codeblock and blockquote markdowns. So I've been applying it to things like "Proper" names or "Proper acronyms" (subjective, I know), file paths or names, file extensions and what I'd consider to be synonymous from an sysadmin perspective with markingdown inline "code" from a developer perspective. Similar to how an inline reference to a functional call, say rnd() ought to receive this markdown, it seems to make sense to me that, it would be used to distinguish, say an inline reference to .jpg, since they're is functionally the same thing from each discipline's perspective (or I think they are).

And, with an eye to readability and formatting considerations, I'll generally use it more liberally to help visually "breakup" a wall of text effect or string of acronyms/jargon and more conservatively when the readability/formatting seems fine, or using it to some stricter standard would make things less readable to my eye.

Anyone have any thoughts, opinions, compliments, trade secrets or other assorted combinations of words they'd like to share to help enlighten me?

10
  • 3
    Whoah, tl;dr... Sep 14, 2012 at 2:47
  • @MarkHenderson Good to know. Maybe I'll just paste my most recent posts in as reports I have to get done for work, confident in the certainty no one will bother reading past an opening paragraph or two. Sep 14, 2012 at 3:12
  • 2
    It is easy to understand why formatting rules on ELU, and other exchanges might be different from here. It is best to stick to the norms of a specific site.
    – Zoredache
    Sep 14, 2012 at 3:38
  • 5
    @HopelessN00b - actually, you know what I did read? The parts with backtick higlighting and <kbd> tags. So there you go, maybe that's worth noting... Sep 14, 2012 at 4:05
  • 2
    All I saw was a title and a massive wall of text but the title probably told me all I really need to know about the question. The "right way"? Just follow the general trend used by other medium to high ranked members. Sep 14, 2012 at 6:30
  • @MarkHenderson actually, you know what I did read? The parts with backtick higlighting and <kbd> tags. Right, which I'm now going to claim was part of my plan to make exactly that point all along. ;) Sep 14, 2012 at 7:27
  • 1
    that formatting markdown has a specific meaning, don't use it like that some people in ELU are grammar Nazis, that's why, whoops... I generally use backticks for any verbatim text; additionally, I also use backticks for quoting in comments since blockquotes cannot be used in comments.
    – Lie Ryan
    Sep 18, 2012 at 16:26
  • @LieRyan. Yeah, I figured ELU.SE was probably a ---grammar Nazi--- "sensitivity-challenged," pedantic. Individual, but was more using it as an example of... differing opinions, even around here, on the "proper" use of formatting elements. Sep 18, 2012 at 16:46
  • You seem to use the tilde in an unusual way. Sep 23, 2012 at 12:37
  • @SamuelEdwinWard Hence this thread. Sep 23, 2012 at 19:30

4 Answers 4

10

Use backticks and blockquotes and code blocks however you damn please. I have the following conventions when I'm editing:

  • Executable names, backticks
  • Flows, backticks (e.g. Go to Tools > Options and un-tick the corrupt my data randomly checkbox)
  • Config files, codebox
  • Single-lines from config files, backticks or codebox (depending on my mood)
  • Quoting from a linked page, quotebox
  • Quoting from the original, or another, question - quotebox
4
  • Thanks to everyone, (but Mark in particular). This whole discussion/"thread" was really helpful to me. Or will be once I get my head around markdown. It really *does* choke orphans, rape neurons and everything else. Sep 18, 2012 at 11:34
  • I put example links in backticks when in a paragraph. Sep 20, 2012 at 17:26
  • Is "quotebox" the one where you start the line with a >? Sep 23, 2012 at 12:31
  • @SamuelEdwinWard - yep Sep 23, 2012 at 20:23
5

What Mark said. Plus

I use

  • backticks anytime I want a snippet of syntactic code (programming code, CLI, file spec, etc) I want to stand out.
  • ">" for quoting someone else, only. Quoting Wikipedia, the OP, another person, etc.
  • The four space thing for longer/multiline chunks of syntactic code (config files, programming, whatever)
4

Generally, "make your post look like an O'Reilly Book" is good advice, provided you have one on your desk (I think most of us do).
When editing, "Make it readable" is pretty much the guiding advice -- If it looks better when you're finished you did it right :)

Generally that means backticks for commands, Quote blocks for quotations/citations, and code blocks for code.
The KBD tag does this and can be useful for listing keystroke sequences, but common sequences are often represented unix-style in backticks (^C).

I liberally make an exception to the above in the use of backticks rather than quote boxes when quoting the original question inline in my responses (basically if the quote box would be ugly I use backticks) -- this is because the subtle visual distinction between backticks and quote blocks is easily missed (backticks are monospaced - like mini-code blocks).

2

Now that you've posted the Readers Digest version... You edit looks essentially fine to me and I see nothing wrong with the way you've formatted it. The only thing I would suggest is to try and add a blank line between sections when they get so long, as it greatly aids readability.

TL;DR, in my opinion the post you're referring to looks better after the edit.

You must log in to answer this question.

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