Examples are the best Documentation to learn.
If you are deeply knowledgeable about some library or language, examples become less valuable and the straight forward API documentation becomes essential.
Examples are the best documentation
51–60 of 179 posts
Re: Examples are the best documentation
#52They are not the “best.” They are helpful. I am tired of rudimentary docs that only have examples.
Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.
Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.
Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:
Just put it in a JLabel.
Re: Examples are the best documentation
#53php.net was great for this back in the 2000s.
Re: Examples are the best documentation
#54Code examples can be executed as unit tests to prevent documentation regressions / bitrot in ways human language can't
But now with LLMs maybe they could begin to check for instance API documentation.
Re: Examples are the best documentation
#55Earlier quoted context omitted.
No. Examples are there to show how to use this method, and other methods in conjunction. You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
> because you missed a config, or a preparation step If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context. > don't understand how to process the results Not sure when this would be the case. Do you have an example in mind?
Real world isn't about calculating a fibonacci sequence.
Real world is usually a combination of
- read data
- trasform data
- obtain auth
- prepare data in proper formats
-
- get results back. Perhaps an error? A stream? A specific format? Could we do retries?
That's why a full example would look like this: https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"
Re: Examples are the best documentation
#56Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples.
For example:
https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar
If you're writing docs for your project, consider following the Perl documentation style. Fortunately, that style is itself well documented:
https://perldoc.perl.org/perldocstyle#Description-and-synops...
Re: Examples are the best documentation
#57While there is often a lack of examples in documentation, a lack of cogent conceptual explanations is unfortunately even more widespread.
Re: Examples are the best documentation
#58This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function pr…
> £JOB
Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name?
Stop throwing my entire world view out of order please.
Re: Examples are the best documentation
#59This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function pr…
> £JOB Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name? Stop throwing my entire world view out of order please.
I actually don't know, I just assume the majority of people are americans and that's why they use $. I don't use $ in programming except for string interpolation, so it's never really registered as a variable sigil to me
Re: Examples are the best documentation
#60php.net was great for this back in the 2000s.
I agree. When we moved to Python, I really missed all the examples that php had that the Python docs didn't.