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

131–140 of 179 posts

Re: Examples are the best documentation

#131

Post by deaddodo »

OptionOfT wrote: post #120
harimau777 wrote: post #70

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 nee…

The annoying part about Python is that searching for the python docs is hard. E.g. "Python rstrip" (without quotes) in DuckDuckGo does not lead me to the Python docs on page 1.

I've never had that issue with Python.

Now, languages with common / short names? All the time. Go, C, C++, D, etc; even Rust (especially since all the libraries have similarly ambiguous names related to iron oxide).

Re: Examples are the best documentation

#132

Post by stronglikedan »

harimau777 wrote: post #70

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 nee…

To me, you're describing a specification, a type of documentation, with examples being another type. And I agree that a specification should just list definitions with explanations.

But there's no reason that a document cannot contain both a specification and examples. That's the type I prefer, and that's the type I mostly encounter nowadays. Usually a specification on the left with some examples on the right, maybe even interactive examples.

Re: Examples are the best documentation

#133

Post by ux266478 »

bigstrat2003 wrote: post #28

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .

The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES

Re: Examples are the best documentation

#134

Post by bitwize »

I'd say worked examples and comprehensive references are mutually reinforcing kinds of documentation, meaning you want both. I know I've gotten big mad at JavaScript library/framework documentation that had a few examples but when I actually wanted to learn the API in full, a reference was sorely missing. It was all cutesy "all you have to do is call wango.mumble() with your endpoints and pass the returned object into garthok.narfle() and it will autowire calls from the front end to back-end routes and you can use the time you saved to play with your doggo! :3" tutorial-y stuff. Good for standing up a simple app, but when I had to characterize the framework's behavior somehow I was staring at the source.

PLEASE provide examples and PLEASE provide documentation of every API call's inputs, outputs, and effects.

Re: Examples are the best documentation

#135

Post by adrianmonk »

tmoertel wrote: post #56

Say 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. Fortunatel…

The examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes.

Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are.

In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.

Re: Examples are the best documentation

#136

Post by troupo »

o11c wrote: post #129
troupo wrote: post #31

Earlier 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...

If the type signature isn't enough to fully constrain that, you need to fix your typing. If you have a `Foo` object, it should always be able to do every possible thing a `Foo` can do. If you need to do something first, it should be a required argument to whatever lets you construct a `Foo` in the first place.

Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples

Re: Examples are the best documentation

#137

Post by mlok »

Also : avoid using IT terms in examples (or "self-reference"), it can be confusing. In examples choose a very different field : animals, cars or anything, so that there is a very clear difference between language keywords (what needs to be learned) and the dummy data treated (what can be forgotten after reading).

An example not to follow : https://developer.mozilla.org/en-US/docs/Web/API/Web_compone...

Here we are trying to explain templates and slots, with "slot" as an html attribute and the dummy data is... "slot". This kind of confusion is useless and makes it more difficult. Almost as if the goal was to be difficult.

Re: Examples are the best documentation

#138

Post by voidhorse »

Examples are indeed crucial, but conceptual documentation and contract documentation that describes behaviors that cannot be formally made transparent in the language are equally important, and often missing too. In fact, I'd argue they are more important because an example can be easily misunderstood without this surrounding context.

Re: Examples are the best documentation

#139

Post by cultofmetatron »

probably one of the best uses of LLMs I've found in recent years. Needed to start integrating rabbitMQ into our application in order in integrate an external service. I had never worked with rabbitmq and while the docs for elixir's rabbitmq library were very good, it left me with a lot of open questions. I hopped on chatgpt and told it what my requirements were and it spat out with a boilerplate. for every scenario, I was able to have an example implementation generated. It still took an additional week of tweaking and changing things but This would have easily taken a month of exploratory programming pre chatgpt. Instead, we had a working proof of concept in a day and a half and had a final version deployed to prod in a month.

Re: Examples are the best documentation

#140

Post by o11c »

troupo wrote: post #136
o11c wrote: post #129

Earlier quoted context omitted.

If the type signature isn't enough to fully constrain that, you need to fix your typing. If you have a `Foo` object, it should always be able to do every possible thing a `Foo` can do. If you need to do something first, it should be a required argument to whatever lets you construct a `Foo` in the first place.

Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples

I see nothing there that seems fundamentally problematic, but I'm not writing type definitions for someone's entire commercial API.

Callbacks are always Hell of course.

Post reply on HN