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?
  • 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 '16 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. ;) – Andrea Lazzarotto May 29 '16 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 '16 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. – Andrea Lazzarotto May 29 '16 at 14:39
  • By the way I totally forgot about the useless tags, especially version tags. Would you mind posting that as an answer? – Andrea Lazzarotto May 29 '16 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 '16 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. – Andrea Lazzarotto May 29 '16 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 '16 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? – Andrea Lazzarotto May 29 '16 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 '16 at 21:04
  • 1
    Oh, btw, reject and edit is your friend. Meet with him. He's useful – Braiam May 29 '16 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. – Andrea Lazzarotto May 29 '16 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 May 30 '16 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 '16 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. – Andrea Lazzarotto Jun 1 '16 at 13:30
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.

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

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)

  • 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. – Andrea Lazzarotto May 31 '16 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 '16 at 2:06
  • 1
    @Videonauth nice. :D This is the Chrome version and there is also a user-script available here. – Andrea Lazzarotto Jun 1 '16 at 10:19
  • I've been looking for that one for ages ^_^ – Zanna Jun 5 '16 at 10:42
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. ;-)

  • «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". – Andrea Lazzarotto Jun 3 '16 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 '16 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. – Andrea Lazzarotto Jun 4 '16 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 '16 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. – Andrea Lazzarotto Jun 5 '16 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 '16 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. :) – Andrea Lazzarotto Jun 5 '16 at 14:59
  • 1
    Oh, I see where you going with this now. edited answer. – Elder Geek Jun 5 '16 at 15:18
3

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

Enclose your images with " [] " which allows users to click on that image for detailed viewing.

Example : You can click on the below image because its enclused with []

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

enter image description here

But you cant clic'k on this image below, as its not enclosed with []

![enter image description here][1]

enter image description here

  • 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. – Andrea Lazzarotto Jun 10 '16 at 8:23
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 )

  • 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. – Andrea Lazzarotto May 31 '16 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. – tudor May 31 '16 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 '16 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. – tudor Jun 2 '16 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 '16 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. – tudor Jun 12 '16 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 '16 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. – tudor Jun 14 '16 at 1:45
  • Interesting approach. – Elder Geek Jun 14 '16 at 19:48

You must log in to answer this question.

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