Let's agree on some commonly accepted formatting guidelines

Question

As pointed out by Mark, there is a related question here:

Style guide for questions and answers

Since I went over 2k rep, I liked starting to work on suggested edits and improving formatting in other posts, trying to be precise and careful. However, I constantly see that many suggested edits by a few users are trying to improve the post, but they actually don't.

Let me be clear: I do not want to make names or point a finger to someone. I truly believe their intentions are good and it is their desire to improve the posts. Nevertheless, IMHO we should agree to stick to some formatting guidelines.

I am talking especially about avoiding ugly formatting choices that sometimes get approved too quickly in my opinion. I have thought about a few common cases that should be handled in the following way, but I'd like to read your suggestions as well.

I believe these formatting issues are bad for two reasons:

• they make me feel like this when I see them
• they waste reviewers' time: a perfect edit takes almost the same amount of work as a "meh" one so there is no reason to suggest edits that always need to be fixed :)

Code "pieces"

With this I mean inline code like commands (sudo apt update) and small pieces of output (Error 404). The backticks are meant for code. Please do not use them for something else.

One of the worst thing I've seen recently is randomly putting backticks around everything. For example:

Tech specs

I have a NVIDIA graphics card

Becomes:

I have a NVIDIA graphics card

Menu entries

I really don't like this one...

Click on File → Edit

Becomes:

Click on File → Edit

Code blocks

I'll discuss this later.

My suggestions

• Use backticks for code
• Avoid random text inside backticks
• Use italics for menu entries
• Rule of thumb: Are you putting that into a terminal/configuration file or is it coming from there?
  • Yes → it's probably code
  • No → avoid backticks

Code blocks

That is code on its own line (or multi-line code). There is a specific way to format it (4 spaces in front of each line) and backticks are not the right one.

Please, do not do this:

`sudo apt update
sudo apt upgrade`

Which results in this ugly block:

sudo apt update sudo apt upgrade

Do this instead:

    sudo apt update
    sudo apt upgrade

Which results in this properly formatted block:

sudo apt update
sudo apt upgrade

Bold

It is not very nice to read a text where bold text has been overused for no apparent reason. It goes on and on and on and makes you wanna cry. ;)

It is also extremely disturbing to read inline code that has been made bold.

This leads to the following suggested guidelines:

• Use italics for light emphasis and bold for stronger emphasis
• Bold is not always necessary, sometimes paragraphs are enough to isolate important parts of the content
• Avoid making error messages bold
  • Use a blockquote > for messages coming from a GUI or a web page
  • Use a code block for messages found in the terminal
• Do you think that piece of code needs to be bold?
  • Yes → Listen, ask yourself that question again...
  • No → See, you are doing fine!

Paragraphs

Paragraphs are separated by two carriage returns, i.e. \n\n in more technical terminology. If you see a long text and you want to separate it into paragraphs, do not add two spaces and a return.

• That creates a line break, not a paragraph
• It doesn't save you key strokes (you spend an extra one!)

Your turn

• What is your opinion on this?
• What are your suggestions for improving formatting in posts?
• What are the most common issues you encounter while approving suggested edits that deal with formatting?

Answer 1

This is a wiki, so anyone can add issues they face with edits to one answer to keep it tidy.

What are the most common issues you encounter while approving suggested edits that deal with formatting?

Edits that just add useless tags while missing images, code, spelling, grammar, etc., I just rejected, like five of these in review today alone.

People editing tag descriptions en masse and without even spell checking them.

Errors in spelling and grammer and a lack of clarity bother me most. While it's arguable that these aren't formatting issues they are perhaps the most important part of obtaining and providing useful answers.

Answer 2

Keyboard keys should be enclosed in <kbd> and </kbd> so that it is Esc and not Esc or Esc. (This is one formatting item that has terrible discover-ability in Stack-flavored Markdown, IMO)

Answer 3

I would like to add one more edit suggestion to this set.

Enclose your image with " [] " and make sure it's linked with [...][link-number] or [...](address) which allows users to click on that image for detailed viewing.

Example : You can click on the below image because it's enclosed with [] and followed by another [1]

[![enter image description here][1]][1]

But you can't click on this image below

![enter image description here][1]

Answer 4

I'm sure we all have our own (and likely differing) opinions on what makes a good edit. I'll admit that formatting is likely the least important to me. I'm most concerned about clarity so that the question can be answered or the answer understood. I'll agree that too much BOLD can be annoying but I honestly don't feel the need to italicize File -> Edit as the preceding directive to "click" makes it abundantly clear that these are menu items. The keyboard formatting tags are pretty and clarify that these are keystrokes but again, the word "press" indicates the same thing with fewer keystrokes. I agree that commands should be commands although I'm not convinced that 2 commands need to be a

code
block

Instead of issue code

and then block

I'll go on to say that accurate tagging is helpful so that specialists can find their area of expertise. Grammatical and spelling errors that make a post difficult to understand are likely my pet peeve. (I also laugh at bad subtitling when watching a movie).

All things considered I think formatting is the least important factor in editing.

Disclaimer: These are my opinions and don't necessarily reflect the views of Stack Exchange or the community at large. ;-)

Answer 5

While I agree with most of your bold-related points, I disagree that bolding is something to be avoided in extremis.

As discussed in a comment session with a higher-rep user recently, I have learned to use bold across all SO sites as a way to make the question clear without having to read it in entirety - namely, two things will always be bolded:

1. The actual question (since it may be more specific than the headline, and is not always best-placed right at the top or right at the bottom), and
2. Anything that specifically makes it different to other questions (thereby demonstrating research).

Basically this allows a knowledgeable reader to skip most of the question and establish if they're going to be able to answer the question (or had the same experience).

While bold may be painful to some, I find that using it this way results in a faster read if you know the topic very well, and less incorrect answers, and less marks as duplicate.

That being said, based on the style of your question above, I would have used bold differently, but less bold overall, if I had been asking the question. ;-) (But not by much. :-p )