News for hackers. Stuff that matters.
Re:Examples Are the Best Documentation by scubbo on Friday October 10, 2025 @11:49AM (#45540327)
> 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.

Re:Examples Are the Best Documentation by sfn42 on Friday October 10, 2025 @01:39PM (#45541626)
Nobody said don't add examples. Just don't do it before creating proper API docs.
Re:Examples Are the Best Documentation by scubbo on Sunday October 12, 2025 @03:01PM (#45560797)
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!