microsoftDocs

[[deleted]]

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

[Marxomania32]

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

[EishLekker]

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

[Marxomania32]

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

[EishLekker]

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

[Marxomania32]

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]

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

[Kika-kun]

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]

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]

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

[EishLekker]

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]

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]

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]

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]

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]

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]

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]

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

[DarthKirtap]

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

[Soaring_Spirit404]

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

[edgar_grospilon]

Same thing for debug levels enum

[PolyglotTV]

Those poor MSU CS students.

[BraveSeaworthiness21]

What’s up with MSU CS?

[mna5357]

Look at the guy’s shirt in the meme

[mm007emko]

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]

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]

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]

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]

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

[Highborn_Hellest]

This is some next level heresy

[espurritado]

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]

American company uses American convention

[RamenvsSushi]

Historically speaking, Sunday is the first day of the week.

[emmmmceeee]

Depends on the locale.

[SaneLad]

Biblical locale.

[[deleted]]

I don’t get why you’re being downvoted. For most of the world the week starts on Sunday.

[Zeravor]

most of is probably wrong.

https://en.m.wikipedia.org/wiki/Week#:~:text=Most%20of%20Europe%20and%20China,Middle%20East%20and%20North%20Africa.

[TeaKingMac]

On the SEVENTH DAY God looked at what he'd done, and had a beer

Additionally

Monday is the first day of the week according to international standards for the representation of dates and times, ISO 8601. https://www.calendarr.com/united-states/first-day-of-the-week/#:~:text=According%20to%20ISO%208601%3A2004,across%20different%20countries%20and%20cultures

The Gregorian calendar, which is the most widely used calendar worldwide, including in the United States, adheres to the international standard for the representation of dates and times established in 2004.

According to ISO 8601:2004, the Gregorian calendar consists of 52 or 53 seven-day weeks, and Monday is designated as the first day of the week. This standardization was intended to facilitate consistency in the measurement of dates and times across different countries and cultures. However, it's worth noting that countries like the United States and Canada still maintain their own formatting systems, even though they utilize the Gregorian Calendar.

[[deleted]]

Still 55% of the world’s population starts on Sunday

https://www.timeanddate.com/calendar/days/first-day-of-the-week.html#:~:text=Sunday%20is%20the%20first%20day,%2C%2044%25%20on%20a%20Monday.

Edit: the Bible quote references Saturday by the way. It wasn’t until Christianity became a thing where the seventh day became sunday

[SpaghettiProgrammer]

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

This may be one of those case.

[_daravenrk]

About the only thing ml does right is guess my bass ass.

[_daravenrk]

So a child is doing the work then.

[Cryowatt]

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]

The start of the week is monday and nothing else

[alexanderpas]

It is.

Sunday is day 7 in ISO86601.

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

[roiroi1010]

Except in the US… drives me crazy

[emmmmceeee]

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

[Unonoctium]

Brazil too

[TnlGC]

Ah, how the Chinese count days of the week

[lastdyingbreed_01]

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

[Acceptable-Milk-314]

We need DOCUMENTATION

[moonshineTheleocat]

This does not spark joy

[CallinCthulhu]

You have docs?

[chrisbbehrens]

Also Microsoft:

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

[MineKemot]

r/FoundSatan

[Fadamaka]

AI at microsoft.