15

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 FileEdit

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?
24
  • 2
    "What are the most common issues you encounter while approving suggested edits that deal with formatting?" My pet hate is edits that just add useless tags while missing images, code, spelling, grammar etc, I just rejected like five of these in review. This comes up from time to time, you will never get every one to agree on guidelines, they are mostly your subjective opinion, for example, your Menu entries, I have no issue with using code for this, it makes it stand out, I see no reason why italics is better, you just seem to like italics.
    – Mark Kirby
    May 29, 2016 at 14:33
  • 2
    Menu entries are not code. Do you type File > Edit somewhere? Maybe the HUD... :D But seriously, those are things you click on. Italics are semantically made for emphasis. That's what they have been used for since people invented them here a few centuries ago. ;) May 29, 2016 at 14:37
  • 5
    It really does not matter that much as long as it is emphasized is my point, there are bigger issues to worries about when editing.
    – Mark Kirby
    May 29, 2016 at 14:39
  • «you will never get every one to agree on guidelines» You misunderstood the post. I am not forcing these specific suggestions as law. This Q has been opened to come up to guidelines together. «they are mostly your subjective opinion» Actually they are based on the semantics of different Markdown blocks (or HTML tags) and typographic conventions used in the western world as documented in many books about type and graphic design. May 29, 2016 at 14:39
  • By the way I totally forgot about the useless tags, especially version tags. Would you mind posting that as an answer? May 29, 2016 at 14:41
  • 1
    Sure, I will make it a wiki for others to add what annoy them about edits too. FYI, I agree with the rest of the post, I just don't think that one thing is a big deal. Here is a related question too meta.askubuntu.com/questions/89/…
    – Mark Kirby
    May 29, 2016 at 14:44
  • I didn't found that link before, thank you for pointing that out. I will post it at the top of my Q. May 29, 2016 at 14:51
  • There are more I am sure, I will post them if I find them, having a new question to remind people never hurts :)
    – Mark Kirby
    May 29, 2016 at 14:52
  • By the way, it would be nice and beneficial for all of us if the people who downvoted the question could also share their opinions on the topic. If we don't know why you disagree with formatting posts in a way accepted by consensus, how can we listen to your point of view? May 29, 2016 at 16:40
  • Any formatting that doesn't make sense shouldn't be used. Bold and italics should be sparingly used, and most of posts don't need them. Code blocks should only be used for stuff people might copy and paste somewhere, or to read shell output and errors. Most of my post use very little or no formatting, therefore they are easy to read.
    – Braiam
    May 29, 2016 at 21:04
  • 1
    Oh, btw, reject and edit is your friend. Meet with him. He's useful
    – Braiam
    May 29, 2016 at 21:05
  • «Code blocks should only be used for stuff people might copy and paste somewhere, or to read shell output and errors» Yes, agreed, that's exactly what is written in my Q as well. «reject and edit is your friend» The point of the Q is that it would be much easier if suggested edits were formatted properly in the first place. One would hope that the majority of edits could be approved even without editing. May 29, 2016 at 21:30
  • 2
    @Zzzach... Please, don't use HTML tags for tasks you can achieve using Markdown. There are cases where going directly for HTML is necessary to achieve a thing, but they are rare. Also simply writing <pre>...</pre> is not the same a s a Markdown code block indented with 4 spaces. It's <pre><code>...</code></pre> instead - and you have to pay attention to your line breaks or it will look weird! TL;DR: The average poster/editor should normally not use any HTML.
    – Byte Commander Mod
    May 30, 2016 at 10:06
  • 1
    There are a few things in the post that I disagree with, but overall it's good so a +1.
    – user364819
    May 30, 2016 at 13:55
  • 1
    @anonymous2 I think your edit is perfectly fine. Maybe also xymon-client could have been made xymon-client but italic text is still acceptable IMHO. Jun 1, 2016 at 13:30

5 Answers 5

8

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.

2
  • 1
    Errors in spelling, grammer and a lack of clarity are my pet peeves.
    – Elder Geek
    Jun 5, 2016 at 15:21
  • @ElderGeek feel free to add those in the community wiki answer. :) Jun 10, 2016 at 21:57
14

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)

4
  • Very good point. Unfortunately Markdown does not have a shortcut for this, so we need to rely on a probably not very famous HTML tag. May 31, 2016 at 20:43
  • 3
    There is a nice tool for Firefox and Chrome to format those HTML tags easily link for firefox
    – Videonauth
    Jun 1, 2016 at 2:06
  • 1
    @Videonauth nice. :D This is the Chrome version and there is also a user-script available here. Jun 1, 2016 at 10:19
  • I've been looking for that one for ages ^_^
    – Zanna Mod
    Jun 5, 2016 at 10:42
4

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]

enter image description here

But you can't click on this image below

![enter image description here][1]

enter image description here

1
  • 1
    The fact that you can click on the picture is not that it is enclosed with [] but it is linked with [...][1] or [...](address). :) Nevertheless it's a good tip, although screenshots should be cropped in the first place to avoid having to open them. Jun 10, 2016 at 8:23
3

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. ;-)

8
  • «I'm not convinced that 2 commands need to be a [...]» Look what happens on mobile. :) i.imgur.com/j0GNHBT.png I agree that italic is not mandatory for menu items, mine was mostly an attempt to say "never use backticks for menus". Jun 3, 2016 at 16:56
  • Ok, I see that but I would never combine 2 commands on one line as in your example. I would command /n/n command
    – Elder Geek
    Jun 4, 2016 at 4:38
  • That means a fake code block with a ugly aspect... :-P The one line is caused by the mobile style, not by the user. Even if you type a return, it doesn't show on a smartphone. Jun 4, 2016 at 9:52
  • If a page isn't rendered properly on your smartphone, that doesn't sound to me like a policy question. It's either a bug in your smartphone software or a configuration question requiring information regarding what smartphone, what software you are using, etc.
    – Elder Geek
    Jun 5, 2016 at 12:40
  • It's not a bug "in my smartphone". As a matter of fact that screenshot was taken with the Chrome developer tools (yes, it shows the same on a real phone, I just wanted to get a screenshot quickly). Anyway, it's not even a "bug" in the CSS of the website. Backticks are to be used for single line code only, therefore there is no reason why the CSS should support showing multiple lines correctly. Jun 5, 2016 at 13:50
  • Perhaps I misunderstood you. I thought you meant that command and then command were being converted to a single line on your phone.
    – Elder Geek
    Jun 5, 2016 at 14:08
  • command\ncommand shows as command command and it makes sense because white space collapses in HTML, unless you are in a <pre> tag or you force it through CSS. :) Jun 5, 2016 at 14:59
  • 1
    Oh, I see where you going with this now. edited answer.
    – Elder Geek
    Jun 5, 2016 at 15:18
2

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 )

9
  • 1
    I agree with you. I don't think I said to avoid bolding in extremis, I think I sad to avoid overusing it. Your suggestion seems quite appropriate and it represents using bold text sparingly, so +1. However, multiple lines bold text is the worst thing. If you make so much text bold that you can read only that, it is probably too much. May 31, 2016 at 8:50
  • Yes, I'm sorry. I didn't mean to imply that was what you said, but how it seems to be being applied. Your example, however, only demonstrates bolding 1.5 sentences, which may be appropriate in certain circumstances, IMHO. May 31, 2016 at 23:14
  • I don't mind the bolding. What I do mind are entire sentences bolded and italicised - this answer, for example, demonstrates a reasonable use. Your git question, though goes overboard.
    – muru
    Jun 2, 2016 at 9:16
  • My git question exactly follows this guideline. Your solution was to entirely remove all emphasis. Furthermore, your response to my query about formatting was terse and unhelpful, so I flagged your comment as such and it was removed. Enough said. Jun 2, 2016 at 23:51
  • 1
    Personally, I think that encouraging skipping most of the question runs the risk of misunderstanding with a commensurate decline in the value of the result. Bolding of step headings and especially warnings does however seem appropriate. The first to help insure that a user doesn't miss a step in implementing a solution and the second to help insure that unrecoverable errors aren't introduced.
    – Elder Geek
    Jun 11, 2016 at 19:26
  • @ElderGeek In my experience it happens more frequently than not, due to time constraints, so this more mitigates the issue for knowledgeable persons. Jun 12, 2016 at 22:52
  • 1
    If something is worth doing it's worth the time to do it right. I don't see how encouraging skipping over most of the question and only reading what is bold could result in a more knowledgeable person. Perhaps it's unclear just to me.
    – Elder Geek
    Jun 14, 2016 at 0:07
  • @ElderGeek That's the opposite of my statement. The bolding is to help more knowledgeable people, not to produce more knowledgeable people. If the reader has already read all the other questions in that area, then it makes no sense to make them read/do everything again. xkcd.com/806 Bolding helps them distinguish how this question is different from others and reduces the chance of being marked as a false duplicate, in my experience. Jun 14, 2016 at 1:45
  • Interesting approach.
    – Elder Geek
    Jun 14, 2016 at 19:48

You must log in to answer this question.

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