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?

  • 3
    Whoah, tl;dr... – Mark Henderson Sep 14 '12 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. – HopelessN00b Sep 14 '12 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 '12 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... – Mark Henderson Sep 14 '12 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. – John Gardeniers Sep 14 '12 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. ;) – HopelessN00b Sep 14 '12 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 '12 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. – HopelessN00b Sep 18 '12 at 16:46
  • You seem to use the tilde in an unusual way. – Samuel Edwin Ward Sep 23 '12 at 12:37
  • @SamuelEdwinWard Hence this thread. – HopelessN00b Sep 23 '12 at 19:30
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
  • 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. – HopelessN00b Sep 18 '12 at 11:34
  • I put example links in backticks when in a paragraph. – Bill Rosmus Sep 20 '12 at 17:26
  • Is "quotebox" the one where you start the line with a >? – Samuel Edwin Ward Sep 23 '12 at 12:31
  • @SamuelEdwinWard - yep – Mark Henderson Sep 23 '12 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 .