10

I noticed my answer to a question was revised and approved for no apparent reason other than markdown preference.

Question

What is the preferred formatting of an ordered list using markdown? I can't find a preference for numbered lists in the Style Guide for questions and answers. On a "Stack site" like this that uses markdown syntax that doesn't care, it might seem nitpicky. But also considering syntax wasn't targeted for community revisions, should a best practice be defined?

I didn't edit the Style Guide as its unclear to me how to build consensus, so I posted this question. It's also not clear to me if more appropriate that changes should be made on the formatting help page?

Background Rationale

In my original post I used a nonordinal number (0.), intentionally not defining index. The edit changed placeholders in favor ordinal numbers (1., 2., ... N.) to define an index.

Although it is syntactically correct, when edited, using ordinal numbering seems less flexible or clear (in a diff); creating a cascading change effect.

2
  • 8
    Thank you for asking here rather than starting an edit war!
    – dessert
    Commented May 17, 2018 at 22:30
  • 1
    I edited to clarify my question is about style guide best practices for lists, and if they should be defined. I feel the answers I'm getting so far fall short of addressing this or more appropriate way to proceed. Commented May 18, 2018 at 17:25

2 Answers 2

12

tl;dr: Output matters, the rest is up to you.

You’re free to use whatever numbering scheme you want as long as it gives the correct output. There is no preferred way, and this is good – needlessly limiting people’s ability to produce the desired output serves no purpose and can even be harmful: Too many rules alienate users from writing posts, and that’s definitely not what we want.

As the output shows, there is no difference between a list numbered with any 0 or 1

0. a
0. b
0. c
  1. a
  2. b
  3. c

and a list using the actual numbers that appear in the output as well:

1. a
2. b
3. c
  1. a
  2. b
  3. c

The first number you use is the starting number for the list (but both 0 and 1 give 1), so to begin with 4 you could do 4., 5., 6. or 4., 4., 4. or even 4., 0., 10., the output is the same. In the case of your answer the editor just wasn’t aware your syntax was fine.

Ask Ubuntu’s formatting help page is a single page with everything you need to know about markdown by design; let’s keep it as simple as possible. It says:

A numbered list:

1. Numbered lists are easy
2. Markdown keeps track of the numbers for you
7. So this will be item 3.
9
  • Thanks for the feedback. I appreciate the effort of your explanation as it may help others, but I understand markdown syntax. My question is actually more concerned with the "Style Guide" preferred by askubuntu.com. Is there a "best practice?" Should it be defined or left ambiguous? (I understand, many folks just have difficulty making a list in markdown, and it might be asking a lot to define it. ) Commented May 18, 2018 at 0:51
  • @mikestewart See my edit! I’ve never seen this Style Guide you linked before, but AU has an extensive formatting help page.
    – dessert
    Commented May 18, 2018 at 5:55
  • 1
    “Markdown keeps track of the numbers for you” this is actually quite misleading. The point is Markdown does not look at the number at all and simply outputs a <li> tag. Commented May 20, 2018 at 15:13
  • 1
    @AndreaLazzarotto That’s not totally true: As I explain in the third paragraph, the first number you use is the number the list starts with in the output. It works!
    – dessert
    Commented May 20, 2018 at 15:19
  • @dessert, yes my previous comment was not very precise. It only looks at the first number, the following numbers are ignored. The numbering of the bullets (except the first one) is handled by the browser. Commented May 20, 2018 at 18:42
  • 1
    @AndreaLazzarotto While this is technically true, I can't think of a compelling pedagogical reason to separate the behavior of markdown from that of HTML; this phrasing teaches what works, but not precisely why.
    – jpaugh
    Commented May 29, 2018 at 20:14
  • @jpaugh I am sorry, I am not quite sure I understand what you mean... Commented May 29, 2018 at 20:41
  • @jpaugh If I understand you, I think the reason why you'd want to allow markdown to handle by using a nonordinal number—except perhaps the first item—is for simplicity/clarity in a diff. It's one of the main points I was driving at, and led me to wonder if it should be defined as a best practice in a style guide. ... Since posting, though, I wonder if it's more appropriate to ask/define at the stackexchange level, rather than askubuntu. Commented May 29, 2018 at 21:49
  • 1
    @mikestewart Truly, there are good reasons to do it either way. For example, if you have nested lists, with nested code blocks inside them, numbering manually can help you check that markdown is doing what you expect it to. But, I doubt many folks have written so complicated a post, and I would not expect many stack exchange sites would see the value of a style guide. (Most non-technical users would see little advantage to prefer either way, and see that style rule as arbitrary.)
    – jpaugh
    Commented May 30, 2018 at 14:09
8
  1. Markdown is not perfect, but we can't expect everyone to know LaTeX, so markdown is the easy way for the most common denominator to be able to produce something readable. :-)
  2. Your answer wasn't revised for no apparent reason: all edits need to be approved by 2 reviewers unless the reviewer edits it himself.
    So ubashu probaly saw your edit as the perfect edit and went "Wow, this doesn't need to wait for additional reviewers" edited your edit, didn't change anything and presto: your edit got approved by one single reviewer.
  3. This behaviour is something that more experienced reviewers use sparingly: I normally approve an edit and allow another pair of eyes to have a look as well, but it's understandable in this case

We're all only human...

Except me, I'm a Vorlon... ;-)

6
  • 2
    thanks for the point. I had no idea whatsoever about that edit stuff. I just thought that "mm... that's weird, 0. 0. 0. 0. 0. 0., I'll just make that 1. 2. 3. 4. 5 to make it more sense". That brings up something else - I wouldn't have done that if I knew. But then another review has to review the edit and I can't make my own edits - that irritating edit (1). I click it and it says "this still needs to be reviewed by more reviewers to complete.". Any way to get around that?
    – fosslinux
    Commented May 18, 2018 at 0:41
  • Ha! Thanks... that helps me understand the process. Having my answer revised, then the change accepted left me with questions. I felt kinda violated. :-o Hahah. Ok, totally overstating it ... but woulda been nice to have my avatar next to the answer. So I was disappointed & had questions as to what/why it happened. I feel my answer was best. But had nothing other than opinion to base it on. And didn't want to troll/start an edit war. Commented May 18, 2018 at 1:09
  • Which led me to ask (and I still haven't seen an answer): Whats the preferred way? Should this be part of the Style Guide? Commented May 18, 2018 at 1:11
  • Whatever works for you. If you edit my response, you'll see I use your system, but it doesn't really matter... @mikestewart as to the "violation" : I've got so many edits that got changed to "community edit" because a HTTPS link exists instead of the HTTP link I used back when that was the standard, that I don't care any more: you still got the reputation that goes with the edit...
    – Fabby
    Commented May 18, 2018 at 7:40
  • @ubashu there is a reason for that: better to have 2 or 3 reviewers review those edits than one who could be tired. As you grow in rep you'll see that for close votes, it takes 5 reviewers to finally close a question even if it's a duplicate. ;-) (And no, I didn't invite you for the answer but to draw your attention to the fact that well-intended edits can sometimes be taken the wrong way, so that's why it's good to change the edit reason: Don't just edit, leave a comment why you edited. 0:-)
    – Fabby
    Commented May 18, 2018 at 7:45
  • 1
    @Fabby thanks for that
    – fosslinux
    Commented May 19, 2018 at 0:36

You must log in to answer this question.

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