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

161–170 of 179 posts

Re: Examples are the best documentation

#161

Post by 1718627440 »

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.

help(str.rstrip) in a Python shell? Who needs online docs? In case I want them I also have them offline in Devhelp.

Am I uncommon in that I search for the website/domain I intend to read first and then look for the specific page?

Re: Examples are the best documentation

#162

Post by 1718627440 »

deaddodo wrote: post #131
OptionOfT wrote: post #120

Earlier quoted context omitted.

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

For C there is excellent documentation and tutorials in man pages and info documents. It's in my experience the best you can find short of reading the code yourself.

Re: Examples are the best documentation

#163

Post by 1718627440 »

chaorace wrote: post #107
inetknght wrote: post #74

Earlier quoted context omitted.

I haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of sh…

Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal. If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imaginat…

> I'd have to read (in alphabetical order) the documentation for 6 different command flags.

You now you don't need to skim a man page like a physical directory? It's in a computer, just search for the flag you want to use.

Re: Examples are the best documentation

#164

Post by 1718627440 »

ux266478 wrote: post #133
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

The GNU project choose to separate documentation into reference (man pages) and tutorials and prose (info). It works quite well and in my opinion info is also superior since it is an interactive hypertext system. So you can have cross-references, outlines, alternatives for different audiences, etc. .

Re: Examples are the best documentation

#165

Post by 1718627440 »

csours wrote: post #94

The "Real" documentation is the implementation. Prioritize making the source code available and understandable. Examples are very nice. One way to create examples is with test cases. Test cases can also be packaged with source code!

The user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.

Re: Examples are the best documentation

#166

Post by porridgeraisin »

1718627440 wrote: post #161
OptionOfT wrote: post #120

Earlier quoted context omitted.

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.

help(str.rstrip) in a Python shell? Who needs online docs? In case I want them I also have them offline in Devhelp. Am I uncommon in that I search for the website/domain I intend to read first and then look for the specific page?

> am I uncommon

I think so!

Re: Examples are the best documentation

#167

Post by hatthew »

1718627440 wrote: post #160
hatthew wrote: post #149

Earlier quoted context omitted.

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

> It's inefficient but it works. I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.

The first part of that line is "If you want an example...". If you want to learn about more advanced usage of some function, then you don't want an example, and that line doesn't apply to you.

Re: Examples are the best documentation

#168

Post by 1718627440 »

hatthew wrote: post #167
1718627440 wrote: post #160

Earlier quoted context omitted.

> It's inefficient but it works. I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.

The first part of that line is "If you want an example...". If you want to learn about more advanced usage of some function, then you don't want an example, and that line doesn't apply to you.

What I say is that you think you want an example, but then either you come back later or you don't and ship slightly broken software.

Re: Examples are the best documentation

#169

Post by tremon »

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.

In DuckDuckGo you should be using !py rstrip, that's what the bangs are for. But yes, in general most of the good (third-party) python resources have been killed by SEO spam.
Post reply on HN