Examples are the best documentation
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…
