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

141–150 of 179 posts

Re: Examples are the best documentation

#141

Post by 8note »

marcosdumay wrote: post #103
horsawlarway wrote: post #90

Earlier quoted context omitted.

Personally - what you're asking for is type definitions. And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured. I think the prevalence of example based documentation is because of this trend - don't waste time…

> what you're asking for is type definitions It's the API specification. It's not just the functions and their parameters, it's also an explanation of what they do. > I'm much less interested in the specific arguments, and I'm very interested in "Capabilities" And that's exactly what an API specification provides you, and that examples do not. Examples only tell you how to use the API on the same way that the author…

I really want both. I can follow examples and read specifications, but i likely want the simplest example first if I'm using a tool, and then the specifications after i've used it a few times.

it's much harder to imagine everything a tool can do with only the specs, and I'm not clear what things I'm missing. Examples make it concrete

Re: Examples are the best documentation

#144

Post by nuancebydefault »

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…

https://en.cppreference.com/w/cpp/utility/optional.html Remove the examples and then make sense of _ANY_ of that documentation.

Re: Examples are the best documentation

#145

Post by meander_water »

I often need both. When I pull up a man page for a tool I haven't used before, I go to straight the bottom to look for an example that matches my use case. Once I have it, I lookup the the specific flags and what they do. Examples aren't meant to be exhaustive, but they certainly help onboard new people faster.

Re: Examples are the best documentation

#146

Post by hatthew »

sfn42 wrote: post #99
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…

This is the right answer. Everyone who disagrees with you are amateurs. A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable. Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But t…

I think it's a bit harsh to call everyone who disagrees amateur. However, anecdotally it doesn't feel very incorrect. When I do pair programming with less-experienced developers, I'll often watch them glance at the API docs, skim over the technical details, look at the example, copy paste it, and then be confused why it doesn't work. Then I pointedly suggest reading the specific paragraph that explains the confusion they have.

Re: Examples are the best documentation

#147

Post by joemi »

constant_flux wrote: post #115
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…

Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job? I don't understand the resistance to examples being a part of documentation (and not a bonus).

It shouldn't be an either/or situation. Good documentation should include both the API spec _and_ examples. I believe the person you're replying to was complaining about documentation that's _only_ examples since it seems like that's what TFA was advocating for.

Re: Examples are the best documentation

#148

Post by kajkojednojajko »

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…

There's a neat mental model that there are four kinds of documentation: tutorials, how-to guides, explanation, and reference.

I think that examples fit into the first or the second kind; I'm not too concerned which category they belong to, because the point is that all kinds all have their place.

Source: https://docs.divio.com/documentation-system/ - someone has already linked it in another comment, but I think it's worth replying because the comments in this thread are arguing about which kind they like the most.

Re: Examples are the best documentation

#149

Post by hatthew »

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…

I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true.

1. If you want an example and the docs have an example, great.

2. If you want technical details and the docs have technical details, great.

3. If you want an example but the docs only have technical details, you can still get what you want by spending longer to read and understand the documentation. It's inefficient but it works. Third party examples are also frequently available.

4. If you want technical details but the docs only have examples, you're SOL. You have to hope that the code is available and readable, or just try stuff and hope it works. Third party technical details are rare.

Re: Examples are the best documentation

#150

Post by joemi »

gbalduzzi wrote: post #22

You need both and there are no ways around that. Examples let you grasp immediately how to use the library and provide you good starting point for your integration. Detailed explanation of all params and configurations allows you to solve more complex problems and understand the full capabilities of the tool. I am miserable when any of the two kind of documentation is missing. The only exceptions are very simple libr…

I'm honestly surprised there are people who think that only examples are fine. And I'm equally surprised there are people who think only reference docs are fine. It's so infuriating coming across a project that only has one kind and not the other.
Post reply on HN