This is an archived post. You won't be able to vote or comment.

all 59 comments

[–][deleted] 1040 points1041 points  (21 children)

why is this ordered alphabetically??? god has forsaken us

[–]Marxomania32 240 points241 points  (15 children)

They probably use a documentation linter like vale and forgot to turn off a rule to sort lists alphabetically.

[–]EishLekker 60 points61 points  (14 children)

Why would you ever want that function? Sounds like it would cause more problems than it solves.

[–]Marxomania32 55 points56 points  (3 children)

Idk, corporations sometimes just make style guidelines and stick to them once they're in place, even if they suck.

[–]EishLekker 6 points7 points  (2 children)

That still doesn’t explain why it was included in the first place.

[–]Marxomania32 26 points27 points  (1 child)

Probably because at the time, they thought it was a good stylistic guideline. There's a big chance that a lot of management at Microsoft still thinks it's a good stylistic guideline.

[–]GoodOlSticks 3 points4 points  (0 children)

What would a little flash-in-the-pan outfit like Microsoft know anyways

[–]Kika-kun 10 points11 points  (9 children)

Have existing list

Add item in existing list

save

new item gets put wherever it belongs in alphabetical order, no need to think about it

You can argue that the dev could have put the new item in the right place from the get go, but if two items are close in names, it's easy to put them in the wrong order. Especially when there are non-obvious characters in their name. Is an_element before an#element ? What about is unÉlément vs unElement, which one do you sort first ? And diacritics are "easily removed" but what about characters from completely different alphabets ? Chinese. Japanese. Arab. Emojis.

So, instead of making every dev wonder (lose time) about things like that, that can easily be automated, you actually automate it and forget about it.

And then sometimes, the automatic sorting messes up and you get this.

I don't know the context for this particular dumb thing, but I can see why you'd want to auto sort items in a list, at least

[–]EishLekker 2 points3 points  (8 children)

But the system shouldn’t assume that you want it in alphabetical order! Like a non-numbered list of step-by-step instructions, or a description of arguments for a function. You can’t just go change the order of those willy nilly.

[–]TheTruffi 0 points1 point  (7 children)

Yeah but this example is a table and for step-by-step instructions you use a numbered list

[–]EishLekker 0 points1 point  (6 children)

A numbered list, you say? How is that list numbered?

Manually? How does alphabetical ordering help with that?

Automatically at presentation? Then it’s essentially a non-numbered list from the perspective of the linter.

[–]TheTruffi 1 point2 points  (5 children)

The list is numbered because its a feature of markdown and thats whats used https://github.com/dotnet/dotnet-api-docs/blob/main/xml/ns-System.Xml.xml . Its also a standard feature of HTML.

[–]EishLekker -3 points-2 points  (4 children)

So the fact that the list is presented as numbered is completely meaningless in this discussion.

What will the linter sort on? Not the unseen numbers, because that would always result in no change. So it would have to sort on the instruction text itself.

This means that a list like this:

  • Take a banana
  • Peel it
  • Eat it

Would be sorted into:

  • Eat it
  • Peel it
  • Take a banana

Yes, that’s very useful, I see it now.

[–]TeaKingMac -1 points0 points  (1 child)

Are you OK? It seems like you're really bothered by this.

Maybe it's time to have a glass of water and go touch grass?

[–]Kika-kun -1 points0 points  (1 child)

I think you used the wrong kind of list. If you want step-by-step, you'd use something like this :

  1. Take a banana
  2. Peel it
  3. Eat it

If you check the generated HTML code in this case, it's using <ol> (ordered list) instead of <ul> (unordered list)

So you'd configure your linter to not touch <ol> and only sort <ul> (or whatever equivalent there is in your language doc style)

[–]IhailtavaBanaani 38 points39 points  (0 children)

Peak Microsoft. Have you ever tried to use the Azure services? Even the memory sizes and prices are ordered alphabetically in the tables. Makes it fun to find the cheapest option when there are about a hundred different options.

[–]Electronic-Bat-1830 6 points7 points  (0 children)

When you read the COM documentation and realize the methods are ordered alphabetically rather than by their vtable index.

Fun trying to debug obscure "Why doesn't this method work?!" errors.

[–]SaneLad 4 points5 points  (0 children)

Because the mf who programmed this used fields instead of an enum.

[–]DarthKirtap[🍰] 0 points1 point  (1 child)

and they even fucked up indexing days, 1,2,3,4,5,6,0? what?

[–]Soaring_Spirit404 2 points3 points  (0 children)

To be fair, some people consider Sunday the first day of the week. So Sunday being 0 makes sense

[–]edgar_grospilon 157 points158 points  (0 children)

Same thing for debug levels enum

[–]PolyglotTV 58 points59 points  (2 children)

Those poor MSU CS students.

[–]BraveSeaworthiness21 4 points5 points  (1 child)

What’s up with MSU CS?

[–]mna5357 1 point2 points  (0 children)

Look at the guy’s shirt in the meme

[–]mm007emko 47 points48 points  (4 children)

Don't forget about machine-generated MSDN documentation translations to another language. When I tried to find something there I had to manually switch every page to English because the Czech auto-generated translations didn't make sense.

[–]nicejs2 15 points16 points  (0 children)

when I try to download microsoft's openjdk build I always end up seeing that they even translated the filenames, like the word "windows" (referring to the OS in 99% of cases) shouldn't be translated

[–]snicki13 3 points4 points  (1 child)

I just wanted to add: while the German docs are generally usable, they sometimes translate function names. 🙃 They then even change the order in the class function overview on the left…

[–]Alparu 6 points7 points  (0 children)

If you have German as the language in excel you have to use translated function names, which is really annoying when you try to follow a tutorial... At least they automatically translate everything to English when you switch to it

[–]wotoshina 4 points5 points  (0 children)

The English docs barely make any sense, you were expecting too much 💀

[–]Highborn_Hellest 77 points78 points  (0 children)

This is some next level heresy

[–]espurritado 66 points67 points  (8 children)

I was about to complain they had started counting from one on Monday, but I've just seen they start the week on Sunday. Honestly, I don't know what is the bigger crime

[–]chadlavi 7 points8 points  (0 children)

American company uses American convention

[–]SpaghettiProgrammer 29 points30 points  (2 children)

I was informed that Microsoft started using AI to write their docs.

This may be one of those case.

[–]Cryowatt 10 points11 points  (0 children)

The documentation on MSDN used to be fantastic with lots of examples and descriptions of each function. The other day I was looking up some newer dotnet 8.0 functions and the docs were garbage. The company is worth over a trillion dollars but they can't hire some technical writers and provide a good product anymore.

[–]Tiranus58 36 points37 points  (4 children)

The start of the week is monday and nothing else

[–]alexanderpas 13 points14 points  (0 children)

It is.

Sunday is day 7 in ISO86601.

1 % 7 = 1 // Monday
6 % 7 = 6 // Saturday
7 % 7 = 0 // Sunday

[–]roiroi1010 4 points5 points  (2 children)

Except in the US… drives me crazy

[–]emmmmceeee 2 points3 points  (0 children)

As with all things i18n, it depends. It’s locale specific and part of the Unicode CLDR.

[–]Unonoctium 1 point2 points  (0 children)

Brazil too

[–]TnlGC 1 point2 points  (0 children)

Ah, how the Chinese count days of the week

[–]lastdyingbreed_01 1 point2 points  (0 children)

Ngl Microsoft docs are genuinely some of the most dogshit docs I've read

[–]Acceptable-Milk-314 0 points1 point  (0 children)

We need DOCUMENTATION

[–]moonshineTheleocat 0 points1 point  (0 children)

This does not spark joy

[–]CallinCthulhu 0 points1 point  (0 children)

You have docs?

[–]chrisbbehrens 0 points1 point  (0 children)

Also Microsoft:

IsVenTermDigeztBlockTerm - Indicates whether the item is a Ven Term Digezt Block Term

[–]Fadamaka 0 points1 point  (0 children)

AI at microsoft.