Please do not use code blocks formatting for text that is not code

Question

Formatting dedicated for code blocks should be used exclusively for code and things like compiler options. It is not an alternative version of blockquote formatting; using it as such throws off the operation of accessibility software, like text-to-speech programs used by people with visual impairment. As far as I know, text within code blocks is spelled out letter-by-letter instead of being read as full words. It also messes up user experience in general. From Meta SE:

[Using backticks is] not just distracting, it's semantically wrong. Code formatting is semantic HTML to indicate to a parser that text is code. If we start lying to our parsers, we break tools built on HTML. Consider screen readers: if a visually impaired user configures their software to spell out code tags, or to have an easy keyboard shortcut with a macro called "jump to next code span/block and highlight" for easy copy-pasting, we are significantly disabling their ability to interact with the page. [...]

Code blocks formatting does not present information more clearly than either a blockquote, a list, emphasis, or any combination of them.

I am neither visually impaired nor using software that depends on code blocks formatting, but it is still annoying; text formatted with code blocks often cannot be freely read because one has to use horizonal scroll between reading each single line.

Meanwhile, a recent edit suggestion intended to fix the issue of code blocks formatting being used where blockquote formatting should have been used instead has been rejected as "not improv[ing] the quality of the post [...] unnecessary or [...] confusing". Big yikes. I find it hard to believe that such "old-school" users are not aware of what is already known by a total newcomer who has been here for mere 18 days, so I would rather guess that has to do with something else; in general, it would not be the first time of the regular and the most active users on this site giving an impression of forming a certain club, and I am not in it. However, those issues are off-topic for this thread.

Here is another example I have just found, with an edit suggestion not made by me. It was also attempting to switch code blocks to blockquotes, and was rejected by the post's author.

I am not happy to have included the links to the specific edit suggestion review because it could be seen as "calling out" specific users by mentioning their nicknames. However, I am worried that, without that link, my post would be seen as lacking essence, missing the evidence, not be actionable by anyone, and not be as useful. I am therefore open to suggestions of removing the identification-enabling links, and alternative solutions of the "calling out names" issue in the context of this thread.

---

Down voters are encouraged to join the discussion and leave comments or answers explaining their disagreement. If there is no discourse between disagreeing parties, no constructive consensus could be made; thus, if you actually genuinely care about improving the quality of the site, stating the reasons for your disagreement in explicit words is essential. Until then, I am going to assume those to be down votes made out of spite.

Answer 1

This is one of the things we should heighten awareness of - I guess most of our reviewers are not visually impaired so in the review queue, this does look like a very minor edit.

However, as you point out, it is a significant improvement in readability of any visitors who do use accessibility tools, or in fact any tools to parse page content. I have had a look through the two you linked to and others just to understand the differences, and although I don't use any accessibility tools, if I use a smaller browser window, then it also significantly impacts readability.

So, yes - the guidance on meta.SE that you link to is correct. Please continue to make these types of edits, and flag up inappropriate rejections.

Answer 2

About the two edits themselves:

It was called to my attention yesterday that I was one of the people who voted to reject one of the edits.

I took a look last night to see what happened. When the edit was displayed (shown below) it looked to me like text had been added. We get edits from time to time where people add stuff in (I did it once myself and got yelled at) and unless it really seems needed or an improvement the original author would like be happy about, we tend to reject those.

But while it looked like it to me, and while some separate lines were merged into a paragraph (i.e. the heading of the formal letter which folks these days probably have much experience with) no new content was added.

So on my part it was a hasty edit reject vote and I didn't stop to read the explanation. Votes are not perfect and that's why it takes more than one.

With the color highlighting difference and the strikethrough, I didn't even notice that the formatting had been changed from monospace/codeblock (which possibly the original letter was actually written using an IBM Selectric) to variable space "modern" formatting.

Often all that's necessary is to ask a simple short question "Why was my edit rejected?" ending with a question mark and a mod will look into it for you, and if it makes sense (as in the first case) will override the community voting.

I didn't vote on the other one but I have a hunch something similar may have happened, in the default comparison mode it looks totally different and two folks going through the review queue may have rejected for similar reasons.

Or they may have rejected for the format change and (in this case) longer display length.

I think as people get more used to these edits they'll catch on and look for them, and as @Rene's SEDE search shows us there's a lot of use of the code block function for various reasons (including reproducing the original monospace formatting of the source) that's gone on for years, so there's some challenges ahead.

---

Answer 3

Recommendations:

1. Focus on best practices and guidelines rather than a list of arbitrary "don'ts".
2. Avoid mythologies, either starting them or propagating them. In the main meta you don't get far trying to make a rule or change one without sufficiently large number of convincing examples of harm for all to see. "We all know this is bad, right?" wouldn't cut it there; it shouldn't here either.
3. Avoid making work for others (you are not others). In other words, unless there's a compelling documented reason why users have to do things the hard way, there should not be a rule insisting that they are.

Readability:

Before making a rule, show several actual examples of things using monospace font (via the code block function) that most people agree are actually hard to read, then show how most people agree they are easier to read the other way. Otherwise one is simply mythologizing.

If it's just a case of that the readability doesn't benefit from monospace, that's not a reason to invent a new rule.

Tables:

In some cases monospace font comes in handy. For some tables and some users it's a lot easier than trying to track down the instructions for the New Feature: Table Support

Please note! The instructions include the use of the code block feature to make it clearer!

| A header | Another header |
| -------- | -------------- |
| First    | row            |
| Second   | row            |

and

| left | center | right |
|:---- |:------:| -----:|
| One  | Two    | Three |

Code blocks formatting does not present information more clearly than either a block quote, a list, emphasis, or any combination of them.

Is that always true? Has it been proven? Is it just a mythology?

Remember that Space stuff started in (roughly) the age of Holerith fields and line printers, a lot of the old transcripts and even modern day notifications (did I see some notams or bulletins in some posts?) are sometimes formatted assuming monospacing, and they look worse if you display in modern variable-space font.

It would be a shame if the stuff that does look better in monospace was all moved to variable space because of some pedantic rule rather than what should be guidelines and best practices to maximize readability.

And note, the community has so far there is no support for syntax highlighting which feels hypocritical if we're insisting they can only be used for code.

• Activate Language Sensitive Highlighting for code/script blocks?

---

from https://space.stackexchange.com/a/34094/12102

This seems readable to me, is there an actual problem that needs to be solved here with a "do not use code blocks formatting for text that is not code" rule? Wouldn't a best practices recommendation or set of guidelines better maximize readability without the dead weight of an absolute rule?

*******************************************************************************
 Revised: Dec 29, 2018            486958 (2014 MU69)                    2486958
 *SPECIAL*

 This pre-computed trajectory is consistent with the New Horizons spacecraft
 Kuiper-Belt extended mission, with the planned 3500 km flyby of Ultima Thule
 on 2019-Jan-1 @ 05:33 UTC.

 Trajectories were provided by the New Horizons mission planning team at SWRI 
 and are fits to internal flight-project data that has not been made available 
 outside the flight project.

 To use this official mission trajectory to ...

  A) Generate ephemerides with respect TO the mission target:
      Specify the coordinate center in Horizons as "@2486958" 

  B) Generate ephemerides OF the mission target
      Specify the target in Horizons as "2486958". 

 To instead use the latest JPL ground-based orbit solution (based on the 
 publicly available data) and numerically integrate over an arbitrary 
 time-span with statistical uncertainties of that public dataset, do a 
 look-up in Horizons with syntax "2014 MU69;" or "486958;" or "DES= 2486958;" 
 or "DES= 2014 MU69" or "2486958;" (i.e., with a semi-colon). 

 Note: the object previously had a provisional SPK ID of 3713011.  It was 
 then assigned an IAU number of 486958 such that the primary SPK ID became
 the present 2486958 (2000000 + IAU number).
 
 Trajectory name                            Start (TDB)         Stop (TDB)
 ---------------------------------------  -----------------  -----------------
 20180601_20250101_od141_tcm30_burn_V0.1  1994-Jan-08 00:00  2033-Dec-21 00:00 

versus

---

Revised: Dec 29, 2018 486958 (2014 MU69) 2486958 SPECIAL

This pre-computed trajectory is consistent with the New Horizons spacecraft Kuiper-Belt extended mission, with the planned 3500 km flyby of Ultima Thule on 2019-Jan-1 @ 05:33 UTC.

Trajectories were provided by the New Horizons mission planning team at SWRI and are fits to internal flight-project data that has not been made available outside the flight project.

To use this official mission trajectory to ...

A) Generate ephemerides with respect TO the mission target: Specify the coordinate center in Horizons as "@2486958"

B) Generate ephemerides OF the mission target Specify the target in Horizons as "2486958".

To instead use the latest JPL ground-based orbit solution (based on the publicly available data) and numerically integrate over an arbitrary time-span with statistical uncertainties of that public dataset, do a look-up in Horizons with syntax "2014 MU69;" or "486958;" or "DES= 2486958;" or "DES= 2014 MU69" or "2486958;" (i.e., with a semi-colon).

Note: the object previously had a provisional SPK ID of 3713011. It was then assigned an IAU number of 486958 such that the primary SPK ID became the present 2486958 (2000000 + IAU number).

Trajectory name Start (TDB) Stop (TDB)

---

20180601_20250101_od141_tcm30_burn_V0.1 1994-Jan-08 00:00 2033-Dec-21 00:00

---

Here's another from here:

  An unexpected loss of contact with SOHO occurred on 25 June 1998. The mission
   was recovered and normal operations resumed in mid-November 1998. Despite 
   subsequent failures of all three gyroscopes (the last in December 1998), 
   new gyro-less control software installed by February 1999, allowing SOHO to 
   resume normal operations (and making SOHO the first 3-axis-stabilised 
   spacecraft to operate without a gyroscope).
[...]

SPACECRAFT TRAJECTORY (concatenated trajectories from GSFC FDF):

  For the time-span 1998-Aug-19 to 1998-Sep-25, there is no official 
  trajectory information due to the recovery effort. Therefore, the initial 
  state at resumption of operations 1998-Sep-25 was integrated back to 
  August 19 assuming a purely ballistic trajectory. Trajectory errors 
  during this interval may be significant due to unmodelled dynamics.

  Trajectory name             Start        Stop
  --------------------------  -----------  -----------
  soho_1995                   1995-Dec-02  1996-Jan-01
  soho_1996                   1996-Jan-01  1997-Jan-01
  soho_1997                   1997-Jan-01  1998-Jan-01
  soho_1998a                  1998-Jan-01  1998-Aug-19
  soho_1998a-b_gap            1998-Aug-19  1998-Sep-25 (ballistic filler)
  soho_1998b                  1998-Sep-25  1999-Jan-01 (recovery of contact)
  soho_1999                   1999-Jan-01  2000-Jan-01
  soho_2000                   2000-Jan-01  2001-Jan-01
  soho_2001                   2001-Jan-01  2002-Jan-01
  soho_2002                   2002-Jan-01  2003-Jan-01
  soho_2003                   2003-Jan-01  2004-Jan-01
  soho_2004                   2004-Jan-01  2005-Jan-01
  soho_2005                   2005-Jan-01  2006-Jan-01
  soho_2006                   2006-Jan-01  2007-Jan-01
  soho_2007                   2007-Jan-01  2008-Jan-01
  soho_2008                   2008-Jan-01  2009-Jan-01
  soho_2009                   2009-Jan-01  2010-Jan-01
  soho_2010                   2010-Jan-01  2011-Jan-01
  soho_2011                   2011-Jan-01  2012-Jan-01     
  soho_2012                   2012-Jan-01  2013-Jan-01 
  soho_2013                   2013-Jan-01  2014-Jan-01
  soho_2014                   2014-Jan-01  2015-Jan-01 
  soho_2015                   2015-Jan-01  2016-Jan-01 
  soho_2016                   2016-Jan-01  2017-Jan-01    
  soho_2017                   2017-Jan-01  2018-Jan-01 (prediction Dec20-Jan01)
  soho_2018                   2018-Jan-01  2018-Dec-03 (prediction after Sep 9)

versus

An unexpected loss of contact with SOHO occurred on 25 June 1998. The mission was recovered and normal operations resumed in mid-November 1998. Despite subsequent failures of all three gyroscopes (the last in December 1998), new gyro-less control software installed by February 1999, allowing SOHO to resume normal operations (and making SOHO the first 3-axis-stabilised spacecraft to operate without a gyroscope). [...]

SPACECRAFT TRAJECTORY (concatenated trajectories from GSFC FDF):

For the time-span 1998-Aug-19 to 1998-Sep-25, there is no official trajectory information due to the recovery effort. Therefore, the initial state at resumption of operations 1998-Sep-25 was integrated back to August 19 assuming a purely ballistic trajectory. Trajectory errors during this interval may be significant due to unmodelled dynamics.

Trajectory name Start Stop

---

soho_1995 1995-Dec-02 1996-Jan-01 soho_1996 1996-Jan-01 1997-Jan-01 soho_1997 1997-Jan-01 1998-Jan-01 soho_1998a 1998-Jan-01 1998-Aug-19 soho_1998a-b_gap 1998-Aug-19 1998-Sep-25 (ballistic filler) soho_1998b 1998-Sep-25 1999-Jan-01 (recovery of contact) soho_1999 1999-Jan-01 2000-Jan-01 soho_2000 2000-Jan-01 2001-Jan-01 soho_2001 2001-Jan-01 2002-Jan-01 soho_2002 2002-Jan-01 2003-Jan-01 soho_2003 2003-Jan-01 2004-Jan-01 soho_2004 2004-Jan-01 2005-Jan-01 soho_2005 2005-Jan-01 2006-Jan-01 soho_2006 2006-Jan-01 2007-Jan-01 soho_2007 2007-Jan-01 2008-Jan-01 soho_2008 2008-Jan-01 2009-Jan-01 soho_2009 2009-Jan-01 2010-Jan-01 soho_2010 2010-Jan-01 2011-Jan-01 soho_2011 2011-Jan-01 2012-Jan-01
soho_2012 2012-Jan-01 2013-Jan-01 soho_2013 2013-Jan-01 2014-Jan-01 soho_2014 2014-Jan-01 2015-Jan-01 soho_2015 2015-Jan-01 2016-Jan-01 soho_2016 2016-Jan-01 2017-Jan-01
soho_2017 2017-Jan-01 2018-Jan-01 (prediction Dec20-Jan01) soho_2018 2018-Jan-01 2018-Dec-03 (prediction after Sep 9)

Code blocks formatting does not present information more clearly than either a block quote, a list, emphasis, or any combination of them.

Really?

Remember recommendation number 3:

3. Avoid making work for others (you are not others). In other words, unless there's a compelling documented reason why users have to do things the hard way, there should not be a rule insisting that they are.