11

I have just had half a dozen comments of unnecessary back-and-forth with another user because they told an OP that...

In my opinion error messages should be formatted as text.

... and I didn't immediately realise that by "text" they meant preformatted text, rather than regular text. It turned out they were paraphrasing a passage of the ban FAQ, which says:

Format code, errors, and data as text (using code formatting).

I feel it would be a slight improvement with respect to clarity to rephrase that as...

Format code, errors, and data as code blocks.

... or, as Makyen suggests...

Code, errors, and data should be text formatted in code blocks.

(I considered editing it myself, but the ban FAQ is a locked Meta question.)


P.S.: Originally this question also suggested, as alternative phrasings...

Format code, errors, and data as preformatted text (using code formatting).

... and...

Format code, errors, and data as preformatted text.

... but the comments and answers here have convinced me that the "preformatted" term makes them avoidably clumsy.

14
  • 2
    Hmm, SOCVR proposed that last revision, so if parts of it cause confusion we are to blame.
    – rene
    Commented Mar 30, 2018 at 15:45
  • It was introduced here and I pinged the original author to chime in.
    – rene
    Commented Mar 30, 2018 at 15:52
  • Saying "preformatted text (using code formatting)" is fine; arguably better. I feel condensing it further (at least in your other examples) losses clarity and lessens the stress placed on the issue in a document where we are trying to be crystal clear as to what is beneficial. One of the things we're trying to communicate is the need to have things as text. Begin somewhat less verbose lessens the stress placed on that issue, and requires the user to click-through the link to really understand what is being said.
    – Makyen Mod
    Commented Mar 30, 2018 at 16:02
  • 4
    Hmmm... Perhaps: "Code, errors, and data should be text formatted in code blocks."
    – Makyen Mod
    Commented Mar 30, 2018 at 16:03
  • @Makyen I feel like verbosity is not required to convey that, given that the very next bullet point says "Do not use images".
    – TylerH
    Commented Mar 30, 2018 at 16:04
  • 1
    @TylerH Given how widespread the issue is of using images for code, and how significantly negative the reaction people have to it, I actually prefer a small amount of reiteration.
    – Makyen Mod
    Commented Mar 30, 2018 at 16:10
  • @Makyen That is fair; posting code as images is still a very common problem on SO
    – TylerH
    Commented Mar 30, 2018 at 16:11
  • 5
    They are completely misreading advice not to use screenshots there. Commented Mar 30, 2018 at 17:06
  • @Makyen You might want to make an answer out of your next-to-last comment.
    – duplode
    Commented Mar 30, 2018 at 19:35
  • Isn't the real issue conveyed by the subsequent bullet point in the ban FAQ, Do not use images for text-based information (code, errors, data, etc.).? Would the confusion be resolved by putting the 2nd bullet item ahead of the 1st, to make it clear that text that cannot be inserted as an image should instead be formatted in a readable manner?
    – dbc
    Commented Mar 31, 2018 at 3:34
  • @dbc While switching the order might make sense, I don't think it would make much of a difference with respect to how the specific sentence I mentioned here is worded. (Furthermore, poor formatting of errors and code is an independent issue from screenshots of text, no matter how common the latter is.)
    – duplode
    Commented Mar 31, 2018 at 3:45
  • It needs to be explicit in saying “code formatting” and also explicitly warn against blockquote. Commented Mar 31, 2018 at 6:59
  • 1
    (by the way, the Meta SE version does not contain that part, because it's at an older revision)
    – user202729
    Commented Mar 31, 2018 at 12:27
  • 1
    'Format ... as text' is meaningless. If you can format it, it's already text. It should say 'format ... as code'.
    – user207421
    Commented Apr 2, 2018 at 0:16

2 Answers 2

20

I don't like the term "preformatted text" because that suggests that Stack Overflow supports pasting actual rich text, instead of just supporting plain text that a markdown parser renders to fake up the formatting.

I do like the "code block" or "text (using code formatting)" options though.

4
  • I suggested "preformatted text" thinking about the HTML output. You do have a point in that phrasing possibly suggesting more than was intended (and also being a bit against the spirit of using Markdown to compose posts).
    – duplode
    Commented Mar 30, 2018 at 22:40
  • 3
    It also doesn't make any sense. "Format your code as preformatted text." If it's preformatted why do I have to format it? Commented Mar 31, 2018 at 18:11
  • @LightnessRacesinOrbit "Preformatted" there would mean "this is meant to be displayed as written, so don't apply word wrapping, whitespace collapsing, etc." (the <pre> HTML element is an expression of that). In any case, I can see how it may sound confusing if the phrasing fails to bring forth the association with HTML to a reader.
    – duplode
    Commented Apr 1, 2018 at 4:10
  • @duplode Exactly. While not necessarily technically inaccurate, it is clumsy wording. Commented Apr 1, 2018 at 11:56
7

While I contributed to a grammatical review of the FAQ post, none of my comments or suggestions covered that line.

When thinking about my own tendencies, though, I realize I actually prefer to post errors using quote formatting; my reasoning is that I am quoting a line of text from somewhere else.

That being said, if I didn't use quote text for some reason, I would definitely use pre-formatted 'code' text. So I don't mind either way and would support something similar to this change:

Format code, errors, and data as code blocks.

10
  • 14
    I strongly disagree with using quote formatting for errors. Quote formatting destroys line-formatting, both in how it's displayed and in the automatic conversion to quote format (i.e. when you highlight the text in the editor and click the button). This is useful, sometimes quite important, information in understanding errors, which is completely lost and unrecoverable once the conversion is automatically performed.
    – Makyen Mod
    Commented Mar 30, 2018 at 16:06
  • @Makyen I should clarify that if the error is multiline or unusually long, I do not use quote formatting.
    – TylerH
    Commented Mar 30, 2018 at 16:08
  • 2
    I understand that you might use such formatting intelligently, but I'd rather not even open up the discussion of it in such a document, as it would then require a longer, more nuanced explanation, which people will get wrong/use inappropriately.
    – Makyen Mod
    Commented Mar 30, 2018 at 16:12
  • I agree with @Makyen about this specific document, even though quote formatting for errors is sometimes okay. (FWIW, not formatting errors as code in [haskell] questions almost always has disastrous results.)
    – duplode
    Commented Mar 30, 2018 at 19:33
  • How about a code block inside of a quote block? That seems like it should satisfy both perspectives.
    – David Z
    Commented Mar 31, 2018 at 3:24
  • @David Z: That won't be necessary.
    – BoltClock
    Commented Mar 31, 2018 at 3:25
  • @DavidZ I see that as acceptable but unnecessary, and I don't do it in my posts.
    – duplode
    Commented Mar 31, 2018 at 3:35
  • @BoltClock Could you clarify what you mean by that? I mean, of course it's not necessary for people to use code blocks in quote blocks, but nobody is suggesting otherwise.
    – David Z
    Commented Mar 31, 2018 at 3:54
  • @David Z: I was in the "errors be quotations" camp for a while but I've learned to be comfortable with eschewing quote formatting completely.
    – BoltClock
    Commented Mar 31, 2018 at 3:59
  • 1
    @BoltClock Sure, but I don't really understand what that has to do with saying "That won't be necessary". Maybe it doesn't matter, though.
    – David Z
    Commented Mar 31, 2018 at 4:08

You must log in to answer this question.

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