Re:If someone’s having to read your docs, it’s not “simple”
by kossTKR on Monday June 07, 2021 @11:10AM
(#27423495)
Exactly. Examples always trumps some convoluted explanation.
Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".
Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.
I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.
Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?
Dozens of "Here's how i used this library to do this" would be amazing.
Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".
Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.
I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.
Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?
Dozens of "Here's how i used this library to do this" would be amazing.