stuck writing complex documentation? people complaining that they don’t know how to use your API? unsure how to explain a very abstract concept?

you should try Adding Example Code!

• now everyone knows what you’re talking about
• you can point to a concrete, specific example and explain from there
• now your documentation is rooted in code that actually works
• understanding abstractions is way less headachy when you can see how it works in actual code
• if people still don’t understand something they can play with your example code and build their own intuition
• you can easily turn your examples into unit tests, too!

why write a bunch of vague codeless documentation that nobody is going to understand when you can Add Example Code?

@kasdeya This this this this

This is a BIG PART of why I keep telling everyone that php's documentation is a *master class* that everyone needs to learn from.

The full paragraph descriptions of the API methods are very sensible to read, and every page is overflowing with example code either written by the documentarians directly or shared in comments.

It is so incredibly EASY to get an intuitive grasp of php just from the documentation alone.

@kasdeya making every rust library author read this over and over until they finally get the message

@kasdeya Python's comes in a close second to me, only because some articles are densely written with a dearth of example code that makes certain bits of the API a chore to intuit, but I still cite Python's documentation as top-tier as well.