Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Examples are the best documentation

rakhim.exotext.com

Post reply on HN
Print view View original

61–70 of 179 posts

Re: Examples are the best documentation

#61

Post by squigz »

voidUpdate wrote: post #59
squigz wrote: post #58

Earlier quoted context omitted.

> £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

Oh no my PHPness is showing!

Also, many, many countries use $, like Canada.

Re: Examples are the best documentation

#62

Post by Paracompact »

troupo wrote: post #55
Paracompact wrote: post #46

Earlier quoted context omitted.

> 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"

You don't quote me well. Here's what I actually wrote:

"If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..."

>

Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users).

I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples.

What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.

Re: Examples are the best documentation

#65

Post by abacadaba »

theamk wrote: post #3

Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…

Unfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.

Re: Examples are the best documentation

#66

Post by dewey »

> One popular community-based project in the Clojure world is clojuredocs.org, a site where people contribute examples for built in functions

When I was learning php in school, the examples / discussions on every documentation page were always the most helpful bit.

Re: Examples are the best documentation

#70

Post by harimau777 »

Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function.

Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I need to fix a problem or actually learn the library.

Also having examples is fine, but they should be considered a bonus; not documentation.

Post reply on HN