Who is the paleontologist writing those examples? #11833
Description
Type of issue
Other (describe below)
Description
Dear Microsoft,
Are we coding, or cramming for Jurassic Park 101?
Normal humans do not memorize names like:
Brachiosaurus
Amargasaurus
Tyrannosaurus
Deinonychus
Velociraptor
Mamenchisaurus
Is it so hard to give examples like:
apple, peach, prune, strawberry
cat, dog, squirrel, wolf, lion
These are relatable, pronounceable, and do not require a paleontology degree to follow.
Examples should teach the method, not challenge the reader’s working memory with exotic trivia. Unless your hidden agenda is to make developers fail coding interviews because they can’t recall how to spell Amargasaurus.
I am fine with redundancy in documentation — but redundancy should be in explanation, not in dinosaur syllables. Please consider that many “poor souls” are trying to learn the language feature itself, not to expand their museum gift-shop vocabulary.
A documentation example is successful when:
It demonstrates the feature clearly.
It does not distract the reader.
It lowers the cognitive load, instead of raising it.
Right now, your List samples fail point 2 and 3.
Sincerely (and with empathy for fellow developers),
A reader who prefers apples and cats over Jurassic fossils.
Page URL
https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1.addrange?view=net-9.0
Content source URL
https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Collections.Generic/List`1.xml
Document Version Independent Id
6b64a242-b26e-8204-b8e2-1ed9bba5338c
Platform Id
5c66f225-f5b9-1c51-7fa9-c7031bf4e421