When I'm searching for docs, 95% of the time a single example would suffice. Yet, 95% of the time I can't find one in any official source.
It seems that by default formal technical documentation is targeted towards someone who's deeply immersed in the ecosystem. But many developers have to juggle a lot of "worlds" in their heads daily. When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
Consider this example from the Python 3 docs:
max(iterable, /, *, key=None) Return the largest item in an iterable or the largest of two or more arguments.... [followed by 5 short paragraphs].
You need to know quite a bit about Python in order to understand this:
What * means in the function definition.
means in the function definition. What / means in the function definition.
means in the function definition. What's a "positional-only parameter separator"
What's an iterable.
What are keyword-only arguments.
... continue reading