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

101–110 of 179 posts

Re: Examples are the best documentation

#101

Post by pixl97 »

btbuildem wrote: post #80

This holds true for product documentation as well. Too often docs are just a litany of detailed feature descriptions, which field and button does what, etc. Feature-list type documentation is orders of magnitude less useful than workflow-type documentation. Majority of the time users are concerned with accomplishing tasks, which if the software is well designed, can be grouped, composed, and illustrated with examples…

> than workflow-type documentation.

Yes, for api/token interactions I love examples that show how to generate a token with only permissions for what you are doing. Then pulling said data from API and interacting with it. At least that's how the users that use the product I work on. Security, workflow, and cleanup are great examples.

Re: Examples are the best documentation

#102

Post by skydhash »

nmcfarl wrote: post #79
skydhash wrote: post #9

Earlier quoted context omitted.

[flagged]

I’m not sure if that’s true. The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size. And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.

That's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.

Re: Examples are the best documentation

#103

Post by marcosdumay »

horsawlarway wrote: post #90
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…

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 is using it.

Re: Examples are the best documentation

#104

Post by marcosdumay »

squigz wrote: post #58
voidUpdate wrote: post #33

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

The $ is for variables. And the upper case make it a BASIC variable, instead of something like Perl or PHP.

Some times people put it in angle brackets . I have no idea what system use variables like that.

Re: Examples are the best documentation

#105

Post by parpfish »

for years, i've been secretly wishing that doctests would take off because it seems to really solve two problems at once:

- it puts a simple usage example into the documentation - you get an easy-to-write, quick-to-run little assertion test that ensures basic functionality is saved

Re: Examples are the best documentation

#106

Post by scubbo »

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…

> You optimize for power users not amateurs.

Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.

Re: Examples are the best documentation

#107

Post by chaorace »

inetknght wrote: post #74
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 .

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

Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!

The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.

Re: Examples are the best documentation

#108

Post by 65 »

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 used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.

The best documentation is type references and examples and a line explaining what the function does. Not one or the other.

Re: Examples are the best documentation

#109

Post by WalterBright »

tialaramex wrote: post #41
WalterBright wrote: post #29

Even better if the documentation examples are part of the test suite!

Right, one of the best out-of-box tooling decisions for Rust is that by default, and out of the box cargo will assume all your documentation examples are tests it should compile and execute. This means so long as you run the tests before shipping you basically can't ship with examples you forgot to update after an API change because they either don't compile or don't work. And you might think well, nobody would ship…

The dlang website generator does not succeed unless all the coding examples run successfully.

Re: Examples are the best documentation

#110

Post by childintime »

greenbit wrote: post #45
oneeyedpigeon wrote: post #40

Earlier quoted context omitted.

I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.

I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.

PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.
Post reply on HN