Comment by scubbo
4 days ago
> You optimize for power users not amateurs.
Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.
Nobody said don't add examples. Just don't do it before creating proper API docs.
That's on me - I over-focused on the leading sentences/paragraphs of the replies ("Please don't follow this advice [that examples are the best documentation]"), and missed that the first comment had "Also having examples is fine, but they should be considered a bonus" in the last paragraph. You're right!